Create APInf REST API guidelines

[bajiat]

Consistent behavior e.g. in API error handling is one part of ensuring a good developer experience. To ensure consistency in the APInf REST API(s), we should create guidelines for the API(s). Guidelines would also help our developers and act as a checklist of what needs to be taken into account and help them to follow common patterns and design decisions.

Please note that the guidelines should adhere to industry best practices as much as possible.

Goal

Create a guideline document, which should cover the following items

• versioning
• URL structure
• error handling
• HTTP response codes
• response formats
• pagination
• date and time formatting

References

• Zalando REST API guidelines
• Blog post about API guidelines

[bajiat]

@kyyberi Please comment the required content and potential references

[kyyberi]

• http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
• http://apistylebook.com/design/guidelines/
• Classic https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

[kyyberi]

I would suggest drafting TOC first, review it fast and then write MVP version

[Nazarah]

interested

[mauriciovieira]

I started the TOC in https://github.com/apinf/platform/pull/2815/files, basically follows the initial goal of this issue. I believe it'll grow a bit, from there.

I am still reading the links suggested in the comments.

[mauriciovieira]

I talked to @bajiat today and she told me @matleppa would take over this task.

I closed #2815 because we think it better fits on https://github.com/apinf/docs repository. Also I created https://github.com/apinf/docs/issues/68

[mauriciovieira]

Actually, I just found https://github.com/apinf/docs/blob/master/docs/develop/REST-API/API-Design.md so this task would be to improve that document.

[bajiat]

Closing the issue. See issue https://github.com/apinf/docs/issues/68 for progress