API guidelines discussion

[dustine32]

@tmushayahama What was the API spec that you added in the zoom chat? Can you add that here too?

[dougli1sqrd]

I have opinions about this: I think there are a couple things that I think are fairly fundamental to a good REST API, and I'll outline them here.

Resources

REST works with URIs that traverse different nested "resources". So, each thing between the / represents an object that could be accessed with the API. So, GET /users/123/friends might return a json list of user ids that are friends of the user with id 123. And GET /users would get the list of all resources (a collection). Designing the API in terms of how the resources are related to each other I think is one major important consideration when making a REST API.

HTTP Methods (and idempotentcy)

REST over HTTP wants the HTTP method specs to be obeyed.

• GET requests should not have form data, never modify the state of the server, and be idempotent. This accesses existing data. For example: GET /users/123 would return the state of user with id 123.
• PUT can update server state, but must be idempotent. PUT can create a resource, but must be used when modifying an existing resource. PUT /users/123 with data { "name": "Gandalf" } would update the name field of user with ID 123 to "Gandalf".
• POST is for creating a new resource and is not idempotent. The response to a POST will often include the URI to the resource your just created. POST /users?name=Morgoth would create a new user, and would return you information about the newly created user, like the id: { "id": 124, "name": "Morgoth" }. Crucially though, the POST is minting a new ID for a unique URI that did not exist before.
• DELETE deletes an existing resource. It is idempotent. DELETE /users/124 would remove user with ID 124, and other requests to that resource would be an error (probably 404, not found): GET /users/124 could return {"error": 404, "reason": "resource not found"}.

That's what I have for now. I'll update if I think of anything else.

Idempotent

An operation is idempotent if running it multiple times does not change the state beyond running it the first time. Running an idempotent operation once is identical to running it N > 1 times. For example, setting the name of user ID 124 to "Morgoth" is idempotent because, before the update, the name is "Melkor", and then updating the name yields {"name": "Morgoth"}, and then updating the name again to Morgoth yields {"name": "Morgoth"}, the same result as before.

[tmushayahama]

These are pretty good, one is summary and other is in detail https://geemus.gitbooks.io/http-api-design/en/ https://github.com/WhiteHouse/api-standards

These design practices can be opinionated, but i have seen them being applied on some of the best designed apis out there. You can look no further than GitHub https://developer.github.com/v3/ and my personal favorite is Paypal https://developer.paypal.com/docs/api/overview/

And since this will be a collection of apis, a welcome page like Google's Maps api might help section our apis https://developers.google.com/maps/get-started/

And maybe a change log page https://developers.google.com/ad-exchange/buyer-rest/relnotes

Without repeating the articles, Let's make use of status codes https://developer.mozilla.org/en-US/docs/Web/HTTP/Status rather than saying {response.result :"There is an error, mouse gene not supported and version number has changed"}

For Panther i think GET services/overrep might be a bad endpoint name for panther overrepresentation. It doesn't tell what resources I am getting