Require schemas for APIs #719
Conversation
When consuming an API from a client, a schema makes your life easier. Not only does it provide documentation, but it also can integrate into automated tooling such as type-checkers and code generators. On the back end, it's nice to plug a schema into a unit test to guarantee that the implementation matches the spec. Depending on the system you use, schemas can also be used to generate API docs or test fixtures.
|
In Rails on iOS, we recommend using json-schema |
| @@ -36,6 +36,7 @@ while building applications. | |||
| ### API | |||
|
|
|||
| - Use GraphQL as an API layer when connecting a mobile app to a web service. | |||
| - Use a schema to describe the shape of the inputs and outputs of an API endpoint. | |||
There was a problem hiding this comment.
Here are my opinions. This is what I generally do on a mature project.
| - Use a schema to describe the shape of the inputs and outputs of an API endpoint. | |
| - Use an [OpenAPI schema](https://learn.openapis.org/) to document the shape of the inputs and outputs of an API endpoint. | |
| - When building a REST API, use the [JSON-API](https://jsonapi.org/) spec to determine the shape of API responses | |
| - When using GraphQL and Typescript, use [GraphQL Codegen](https://the-guild.dev/graphql/codegen) to generate type definitions for the API |
There was a problem hiding this comment.
Ooh JSON-API! I know that can be controversial. Any particular reason you like to default to it?
There was a problem hiding this comment.
Ooh JSON-API! I know that can be controversial. Any particular reason you like to default to it?
It's a well-documented opinionated standard, and I haven't come across another public standard that's as fully defined. I actually don't like some of its opinions, but I also don't want to write my own API standards doc on every project.
There was a problem hiding this comment.
Mmm. I think it's the one I've most frequently come across, that's well-supported, and is a good compliment to the HTTP specification.
I've been trying to think of others I've used and enjoyed, but it's been so long I'm coming up short. But I'd be happy with anything which emphasises the spirit of HTTP/the web and provides a standard we can follow.
There was a problem hiding this comment.
Ooh JSON-API! I know that can be controversial. Any particular reason you like to default to it?
Why is JSON-API controversial @JoelQ ? 👀
When consuming an API from a client, a schema makes your life easier. Not only does it provide documentation, but it also can integrate into automated tooling such as type-checkers and code generators.
On the back end, it's nice to plug a schema into a unit test to guarantee that the implementation matches the spec. Depending on the system you use, schemas can also be used to generate API docs or test fixtures.