isc presentation
DESCRIPTION
aporte isc presentacionTRANSCRIPT
-
Fabin Andrs Sabogal (@fvioz)
Good ways to build an api
-
Agenda
Know the standards
Design human readable URLs
JSON as beautiful object
Thinking big
-
Http Method definitions
Know the standards ?
-
Methods
GET means retrieve whatever information
POST used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource
PUT requests that the enclosed entity be stored under the supplied Request-URI
DELETE requests that the origin server delete the resource identified by the Request-URI
HEAD method is identical to GET except that the server MUST NOT return a message-body in the response
http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
-
HTTP status codes
Know the standards ?
-
https://github.com/3scale/httpstatus_cocktails/
API Cocktails, enjoy it and learn it
-
Success codes
200 OK - Response to a successful GET, PUT, PATCH or DELETE. Can also be used for a POST that doesn't result in a creation.
201 Created - Response to a POST that results in a creation. Should be combined with a Location header pointing to the location of the new resource
204 No Content - Response to a successful request that won't be returning a body (like a DELETE request)
304 Not Modified - Used when HTTP caching headers are in play
-
Error codes
400 Bad Request - The request is malformed, such as if the body does not parse
401 Unauthorized - When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser
403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource
404 Not Found - When a non-existent resource is requested
405 Method Not Allowed - When an HTTP method is being requested that isn't allowed for the authenticated user
-
Error codes
410 Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions
415 Unsupported Media Type - If incorrect content type was provided as part of the request
422 Unprocessable Entity - Used for validation errors
429 Too Many Requests - When a request is rejected due to rate limiting
500 Internal Server Error
-
JSON
Know the standards ?
-
JSON
JavaScript Object Notation, is an open standard format that uses human-readable text to transmit data objects consisting of attributevalue pairs. It is used primarily to transmit data between a server and web application, as an alternative to XML.
-
Jeremy Keith
JavaScript is to Java as ham is to hamster
-
The easier your API is to consume, the more people that will consume it.
Design human readable URLs
-
Definitions
Resource: A single instance of an object. For example, an animal.
Collection: A collection of homogeneous objects. For example, animals.
Consumer: A client computer application capable of making HTTP requests.
Third Party Developer: A developer not a part of your project but who wishes to consume your data.
Endpoint: An API URL on a Server which represents either a Resource or an entire Collection.
URL Segment: A slash-separated piece of information in the URL.
-
Choose a root
Here are two common URL Roots:
https://example.com/*
https://api.example.com/*
-
Endpoints
Collections
https://api.example.com/v1/friends
https://api.example.com/v1/employees
Use nouns but no verbsUse plural nouns
-
Endpoints
Resource
GET /friends: List all Frends (ID and Name).
POST /friends: Create a new Friend
GET /friends/1234: Retrieve an Friend object
PUT /friends/1234: Update an Friend (entire object)
PATCH /friends/1234: Update an Friend (partial object)
DELETE /friends/1234: Delete an Friend (partial object)
-
Filtering
Design human readable URLs
Minimize the arbitrary limits imposed on Third Party Developers
-
Filtering
?limit=10: Reduce the number of results returned to the Consumer (for Pagination)
?offset=10: Send sets of information to the Consumer (for Pagination)
?sort=+name,-age: Sort the results based on the specified attribute (ORDER BY name ASC, ORDER BY age DESC)
?fields=name,age,friends: Select the attributes for a results (SELECT name, age)
/comments?filter[post]=1,2&filter[author]=12
-
Deep level
GET /companies/1/departments/1/employes/1
GET /dogs/color/red/state/running/location/park
GET /companies/1
GET /companies/1/departments
GET /departments/1/employees
GET /employees/1
GET /dogs?color=red&state=running&location=park
Use sub-resources for relationsSimplify associations - sweep complexity under the ?
-
How should I show the data?Json as beautiful object
-
Top level structure
{ "data": { }, "errors": { }, "meta": { // non-standard meta-information about the primary data. }, "included": { // a list of resource objects that are related to the primary data and/or // each other ("included resources"). }}
-
Resource structure
{data: { "type": "articles", "id": "1", "title": "Rails is Omakase", "links": { "self": "https://api.example.com/articles/1" "comments":"https://api.example.com/articles/1/comments" }}
}
GET /articles/1
-
Collection structure
GET /articles
"data": [{ "type": "articles", "id": "1", "title": "JSON API paints my bikeshed!", "links": { "self": https://api.example.com/articles/1", "authors": { "self": https://api.example.com/articles/1/authors, "linkage": { "type": "people", "id": "9" } }, "comments": { "self": https://api.example.com/articles/1/comments" } } }],
"included": [{ "type": "people", "id": "9", "first-name": "Dan", "last-name": "Gebhardt", "links": { "self": https://api.example.com/people/9" } }]
-
Meta structure
{ "meta": { "copyright": "Copyright 2015 Example Corp.", "authors": [ "Yehuda Katz", "Steve Klabnik", "Dan Gebhardt" ] }}
GET /articles/1
-
Pagination
{ "meta": { "count": 5,
"pagination": {first: 1,last: 5,"prev": 1,"next": 3,"current": 2,"per_page": 5,"count": 23
}}
GET /articles
-
Errors
{ "errors": { "code": 422, "status": "Invalid Resource", "title": "The current resource was deemed invalid.", "messages": { "name": ["can't be blank"], id_number: ["can't be blank", "is not a number"], "company": ["is too short (minimum is 5 characters)", "is invalid"] } }}
POST /articles
-
Thinking
big
-
Versioning
1. URL: You simply whack the API version into the URL, for example: https://api.example/v2/accounts/foo
2. Custom request header: You use the same URL as before but add a header, for example: https://api.example.com/accounts/fooapi-version: 2
3. Accept header: You modify the accept header to specify the version, for example: https://api.example.com/accounts/foo Accept: application/vnd.api.v2+json
-
Request Headers
-
Versioning, which is better?
1. URLs suck because they should represent the entity
2. Custom request headers suck because its not really a semantic way of describing the resource.
3. Accept headers suck because theyre harder to test.
-
Caching
There are 2 approaches: ETag and Last-Modified
ETag: When generating a request, include a HTTP header ETag containing a hash or checksum of the representation. This value should change whenever the output representation changes. Now, if an inbound HTTP requests contains a If-None-Match header with a matching ETag value, the API should return a 304 Not Modified status code instead of the output representation of the resource.
Last-Modified: This basically works like to ETag, except that it uses timestamps. The response header Last-Modified contains a timestamp in RFC 1123 format which is validated against If-Modified-Since. Note that the HTTP spec has had 3 different acceptable date formats and the server should be prepared to accept any one of them.
-
Rate limiting
X-Rate-Limit-Limit - The number of allowed requests in the current period
X-Rate-Limit-Remaining - The number of remaining requests in the current period
X-Rate-Limit-Reset - The number of seconds left in the current period
-
Resourceshttp://json.org http://jsonapi.org
http://apiux.com
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-
is.html
http://www.toptal.com/api-developers/5-golden-rules-for-designing-a-
great-web-api
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
-
Questions ?
-
Thanks,
Everyon
e