Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Require schemas for APIs #719

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Require schemas for APIs #719

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions tech-stack/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@pangolingo pangolingo Dec 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are my opinions. This is what I generally do on a mature project.

Suggested change
- 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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh JSON-API! I know that can be controversial. Any particular reason you like to default to it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh JSON-API! I know that can be controversial. Any particular reason you like to default to it?

Why is JSON-API controversial @JoelQ ? 👀


### Web

Expand Down