educloudalliance / api-standards Goto Github PK

I would suggest that we would adapt to http://jsonapi.org/ spec when it comes to JSON responses. It has reached maturity of 1.0 and gains a lot of traction.

Full documentation of the JSON API specification includes:

• Detailed format notes that describe conventions in using the JSON API, including document structure, fetching data, CRUD operations on resources, query parameters and handling errors
• Experimental, official and custom extensions for JSON API, including support for performing multiple operations in a single request, implementation of JSON PATCH and adding the profile link relation in a JSON API spe
• Recommendations for using the specification that — while not as official as the formatting convention notes — reflect wider Web services programming paradigms and are suggested so as to provide programmers with a degree of consistency across their other API-related project work
• Example code
• A list of implementation libraries for both client and server side and some related tools, such as implementation tools of JSON PATCH for Ruby, Node.js and Python

See a good blog posting about the spec http://www.cerebris.com/blog/2015/06/04/jsonapi-1-0/

Here's some more thoughts on API standards. Some overlapping but still worth reading and apply where needed to our standards https://github.com/interagent/http-api-design

In Finland it is officially recommended that we use CC BY 4.0 or CC0.
http://docs.jhs-suositukset.fi/jhs-suositukset/JHS189/JHS189.html

It is widely used practise to create own cache on app end to avoid querying API endpoint on every case. This is where rate limiting practices are pushing app / service developers. Are we going to mention this in some part of the guide lines? When not to use app cache and when it might make sense in context of national service architecture?

Keeping in mind that message that has been pushed to field is that you get the information from one source and one source only. Creating app/service specific caches would contradict with this.

The Github rate limiting practise is widely adopted by the industry such as Twitter, Instagram, Hipchat, 4Square. I would suggest that we add that in our practices as well.

Github practise: https://developer.github.com/v3/#rate-limiting