Research and Design API Standards - Githubissues

Pand-Aid / pandaid-api

backend for Pand-Aid pandemic response app

3 stars 2 forks source link

Research and Design API Standards #15

Open bhgrant8 opened 4 years ago

bhgrant8 commented 4 years ago

Summary

Setting standards regarding the naming of endpoints, fields, pagination, timestamps....

Motivation

Standards give a framework/direction for developers of the API to follow, allowing development work to flow quickly.

Frontend Application developers, as "users" of the API appreciate well designed APIs which return data in standardized ways.

Designing and documenting these standards within the repo would aid both groups in understanding and working within a standard language.

Steps to resolve this issue

Research API design principles, what a "well defined" api should look like, example standards from other APIs/open source projects?
draft initial standards, and circulate w/ both frontend + backend teams for feedback
finalized standards and get approvals
recommend some technologies that can help enforce standards in "standardized" ways.

Draft the doc

[ ] Write the doc, following the format listed in these resources:
- (TO DO)
- [Example of a similar article]()
[ ] Add the article to the [docs index]() under the [parent doc] section.

Open a pull request

[ ] Open a pull request with your work including the words "closes #[this issue's number]" in the pull request description

bhgrant8 commented 4 years ago

Adding some examples/background articles to get started:

https://hackernoon.com/restful-api-design-step-by-step-guide-2f2c9f9fcdbf https://www.toptal.com/api-developers/5-golden-rules-for-designing-a-great-web-api

examples:

https://github.com/paypal/api-standards/blob/master/api-style-guide.md https://github.com/WhiteHouse/api-standards https://github.com/hackoregon/2019-backend-cookiecutter-django/blob/master/docs/standards/v1/STANDARDS.md