Skip to content

Commit

Permalink
docs: move why REST over to new template
Browse files Browse the repository at this point in the history
  • Loading branch information
@K-Beicher
K-Beicher committed May 8, 2024
1 parent af8a072 commit 9177ba8
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 45 deletions.
153 changes: 117 additions & 36 deletions why-REST.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,62 +9,143 @@ categories:
- software-architecture
---

<!-- TODO: Update this to match style of other posts -->
::: content-hidden
Use other decision posts as inspiration to writing these. Leave the
content-hidden sections in the text for future reference.
:::

## Introduction
## Context and Problem Statement

::: content-hidden
State the context and some background on the issue, then write a
statement in the form of a question for the problem.
:::

Application programming interfaces (APIs) are ways that applications
communicate to each other through a standard structure or design. There
are several design styles available for building APIs, including Representational State Transfer (REST), Simple Object Access Protocol (SOAP), and GraphQL.
communicate to each other through a standard structure or design. It is
important for a project like Seedcase to chose an API format early on,
bearing in mind both what will work best for the application but also
which resources there are available within the team. The question the
becomes:

## Decision
> Which API technology will best serve the needs of the Seedcase
> project?
We will use the REST architectural style for implementing the communication
protocol between our client and server components, instead of SOAP or
GraphQL.
## Decision Drivers

## Alternatives
::: content-hidden
List some reasons for why we need to make this decision and what things
have arisen that impact work.
:::

### SOAP
<!--TODO docs: Write decision drivers for Why REST-->

[SOAP](https://www.w3.org/TR/soap12-part0/) is a widely used technology for implementing web services. SOAP is
based on the XML protocol and supports a wide range of messaging
formats, such as binary and MIME types, making it quite flexible.
## Considered Options

However, SOAP is fairly complex and heavyweight, which can make it more
difficult to implement and maintain. SOAP requires a lot of additional
metadata and processing overhead, which can result in slower performance
and higher resource consumption. SOAP can also be difficult to debug and
test due to its complexity and lack of visibility in the underlying
communication logs.
::: content-hidden
List and describe some of the options, as well as some of the benefits
and drawbacks for each option.
:::

### GraphQL
There are several design styles available for building APIs, including
Representational State Transfer (REST), Simple Object Access Protocol
(SOAP), and GraphQL. We have looked at REST, SOAP, and GraphQL as
possible API tech for Seedcase.

[GraphQL](https://graphql.org) is an increasingly popular technology for building web APIs.
GraphQL allows for very fine-grained control over what data is requested
and given, so it offers the most flexibility. However, GraphQL can be
complex to set up and maintain, especially for simple use cases. GraphQL
can be integrated with REST API, which is a useful feature especially
when handling large and/or complex requests. So if needed, we could
incorporate GraphQL into existing REST API.
### REST

## Reasons for the decision
<!--TODO docs: complete considered option for REST in Why REST-->

These are the reasons we are deciding on REST:
::: columns
::: column
#### Benefits

- Is lightweight and easy to implement, making it a popular choice for
web-based applications.
web-based applications
- Uses a simple and intuitive set of HTTP methods, which makes it easy
for developers to understand and use.
for developers to understand and use
- Provides a clear separation of responsibilities between the client
and server components, making it easier to develop, test, and deploy
each component independently.
each component independently
- Follows a conceptually simple and traditional approach where the
client sends a request to the server, and the server responds with
the requested data.
the requested data
- Is often simpler to implement and offers better caching mechanisms.
- Has better tooling support and is more widely adopted.
- Has better tooling support and is more widely adopted

:::

::: column
#### Drawbacks

<!--TODO docs: Write drawbacks for REST in Why REST-->

- Item 1
:::
:::

### SOAP

[SOAP](https://www.w3.org/TR/soap12-part0/) is a widely used technology
for implementing web services. SOAP is based on the XML protocol and
supports a wide range of messaging formats, such as binary and MIME
types, making it quite flexible.

::: columns
::: column
#### Benefits

- Based on XML
- Supports a number of messaging formats making it flexible
:::

::: column
#### Drawbacks

- Complex to implement
- Requires additional metadata and processing overhead
- can result in slower performance and higher resource consumption
- Difficult to debug and test due to its complexity and lack of visibility in the underlying communication logs
:::
:::

### GraphQL

[GraphQL](https://graphql.org) is an increasingly popular technology for
building web APIs. GraphQL allows for very fine-grained control over
what data is requested and given, so it offers the most flexibility. GraphQL can be integrated with REST API, which is a
useful feature especially when handling large and/or complex requests.
So if needed, we could incorporate GraphQL into existing REST API.

::: columns
::: column
#### Benefits

- Control over what is transmitted i very detailed
- Flexible
- Can be integrated into REST API
:::

::: column
#### Drawbacks

- Complex to set up and maintain
:::
:::

## Decision Outcome

::: content-hidden
What decision was made, use the form "We decided on CHOICE because of
REASONS."
:::

## Conclusion
We believe that the simplicity, flexibility, and scalability of REST
make it a better choice for the client-server communication needs of Seedcase.
make it a better choice for the client-server communication needs of
Seedcase.

### Consequences

::: content-hidden
List some potential consequences of this decision.
:::
27 changes: 18 additions & 9 deletions why-quarto.qmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ categories:
---

::: content-hidden
Use other decision posts as inspiration to writing these.
Leave the content-hidden sections in the text for future reference.
Use other decision posts as inspiration to writing these. Leave the
content-hidden sections in the text for future reference.
:::

## Context and Problem Statement
Expand All @@ -19,9 +19,15 @@ Leave the content-hidden sections in the text for future reference.
State the context and some background on the issue, then write a
statement in the form of a question for the problem.
:::
A software project like Seedcase needs an easy way to communicate with potential users that are not prime candidates to use Github. The easiest way to do this is by having a website. In order to minimize the work the team needs to do we would like to use the files we maintain in GitHub as the basis for a public website. The question then becomes:

> How do we manage a website with the smallest amount of overhead when we consider that we are already using GitHub?
A software project like Seedcase needs an easy way to communicate with
potential users that are not prime candidates to use Github. The easiest
way to do this is by having a website. In order to minimize the work the
team needs to do we would like to use the files we maintain in GitHub as
the basis for a public website. The question then becomes:

> How do we manage a website with the smallest amount of overhead when
> we consider that we are already using GitHub?
## Decision Drivers

Expand All @@ -45,8 +51,8 @@ writing the documentation for Seedcase itself.
## Considered Options

::: content-hidden
List and describe some of the options, as well as some of the benefits and
drawbacks for each option.
List and describe some of the options, as well as some of the benefits
and drawbacks for each option.
:::

<!--TODO Add the Benefit/Drawback for the other two options-->
Expand All @@ -56,8 +62,9 @@ drawbacks for each option.
Within the R world, a recent new tool came out called
[Quarto](https://quarto.org/). Since its release, it has completely
taken over as the tool to use when working with R and data science. We
will use this tool because it aligns with our [values and philosophies](https://seedcase-project.org/about.html#principles)
for multiple reasons.
will use this tool because it aligns with our [values and
philosophies](https://seedcase-project.org/about.html#principles) for
multiple reasons.

1. It is open source.
2. The documentation is phenomenal and very beginner friendly.
Expand All @@ -84,6 +91,8 @@ What decision was made, use the form "We decided on CHOICE because of
REASONS."
:::

We have decided to go with Quarto as this seems to be the most accessible, as well as being a tool that there is already support for internally in the team.
We have decided to go with Quarto as this seems to be the most
accessible, as well as being a tool that there is already support for
internally in the team.

<!--TODO Update the decision section when the other options have been sorted-->

0 comments on commit 9177ba8

Please sign in to comment.