Best Practices for Architecting 
a Pragmatic Web API 
Mario Cardinal 
Agile Coach & Software Architect 
www.mariocardinal....
Who am I? 
• Agile Coach & Software architect 
• Co-Founder of Slingboards Lab 
• http://mariocardinal.com
3 
Content 
1. REST – What is it? 
2. RESTful or Resource APIs? 
3. Resource APIs or Web APIs? 
4. Web APIs – Best practic...
Application Programming Interface (API) 
 A Web API is a software intermediary that makes 
it possible for application pr...
REST – What is it? 
 An architectural style (extends client-server) 
introduced by Roy Fielding 
 Defines a set of const...
A more lightweight way to build 
services (API) 
 Using URLs to build on Web experience 
 http://myservice.com/api/resou...
Uniform Interfaces (HTTP Verbs) 
GET 
POST 
PUT 
PATCH Updates an existing resource (partially) 
DELETE 
Retrieves a resou...
Resources come from the business 
domain 
 Task Board 
Sticky Notes 
8
Resources are nouns 
 http://myservice.com/api/stickyNotes 
 Verb: GET 
 Action: Retrieves a list of sticky notes 
 ht...
Resources are nouns 
 http://myservice.com/api/stickyNotes/12 
 Verb: PUT 
 Action: Updates sticky notes #12 
 http://...
Most so-called 
RESTful APIs are not 
RESTful at all 
and that’s not a bad thing at all
Rather, most “RESTful APIs” are really 
“Resource APIs” 
http://ServiceDesignPatterns.com/WebServiceAPIStyles/ResourceAPI ...
REST Constraint Resource 
APIs 
Client/Server Yes 
Stateless Not required 
Cacheable Responses Not required 
(Generic) Uni...
Stateless and cacheable response 
 Resource APIs allow the use of cookies 
 Cookies create session state that are partly...
Hypermedia constraint 
 Hypermedia as the Engine of Application 
State (HATEOAS) 
 Hypermedia constraint states that int...
Most so-called Web APIs 
are Resource APIs 
http://en.wikipedia.org/wiki/Web_API 
again, not a bad thing at all. 
Web APIs...
17 
Web APIs – Best practices 
1. URL EndPoint 
 Resources 
 Version 
2. Message Body 
 Content-Type 
3. Error handling...
URL identifies a resource 
 Endpoint name should be plural 
 stickyNotes, collaborators 
 Do not forget relations (busi...
Verbs (actions) as resources 
 Actions that don't fit into the world of CRUD 
operations can be endpoint 
 Change state ...
Use Query to simplify resources 
 Keep the base resource URLs lean by 
implementing query parameters on top of the 
base ...
Paginate using link headers 
 Return a set of ready-made links so the API 
consumer doesn't have to construct links 
them...
Versioning 
 Version via the URL, not via headers 
 http://api.myservice.com/v1/stickynotes 
 http://myservice.com/v1/s...
Message (Content-type) 
 JavaScript Object Notation (JSON) is the 
preferred resource representation 
 It is lighter tha...
Message (Content-type) 
 A JSON object is an unordered set of 
name/value pairs 
 Squiggly brackets act as 'containers' ...
Message (Content-type) 
 camelCase for field names 
 Follow JavaScript naming conventions 
 Do not pretty print by defa...
Message (Post, Put and Patch) 
 Updates & creation should return a resource 
representation 
 To prevent an API consumer...
HTTP caching header 
 Time-based (Last-Modified) 
 When generating a request, include a HTTP 
header Last-Modified 
 if...
HTTP Rate limiting header 
 Include the following headers (using Twitter's 
naming conventions as headers typically don't...
HTTP status codes 
 200 OK - Response to a successful GET, PUT, PATCH or 
DELETE. Can also be used for a POST that doesn'...
HTTP status codes 
 400 Bad Request - The server cannot or will not process 
the request due to something that is perceiv...
HTTP status codes 
 409 Conflict - The request could not be completed due to 
a conflict with the current state of the re...
Security 
 Encryption 
 HTTPS (TLS) everywhere - all the time 
32
Security 
 Authentication 
 Never encode authentication on the URI 
 Always identify the caller in the HTTP header 
 E...
Basic authentication over HTTPS 
 Create a string with username and password 
in the form ”username:password” 
 Convert ...
Security 
 Autorization 
 Return HTTP 403 Status Code if not authorized 
 If necessity, use the body to provide more in...
Documentation 
 An API is only as good as its documentation 
 Docs should be easy to find 
 http://myservice.com/api/he...
Documentation 
37 
URI https://mysite.com:3911/api/members/{id} 
HTTP verb PUT 
Parameters id : Card number of the member....
38 
Do not hesitate to contact me 
mcardinal@mariocardinal.com 
@mario_cardinal 
Q & A
Upcoming SlideShare
Loading in …5
×

Best Practices for Architecting a Pragmatic Web API.

36,182
-1

Published on

This presentation teach how to design a real-world and pragmatic web API. It draws from the experience Mario Cardinal have gained over the years being involved architecting many Web API. This presentation begins by differencing between a Web and a REST API, and then continue with the design process. We conclude with the core learnings of the session which is a review of the best practices when designing a web API. Armed with skills acquired, you can expect to see significant improvements in your ability to design a pragmatic web API.

Published in: Technology
1 Comment
56 Likes
Statistics
Notes
No Downloads
Views
Total Views
36,182
On Slideshare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
749
Comments
1
Likes
56
Embeds 0
No embeds

No notes for slide
  • 8 minutesKeeps people from ‘making up’ verbs Don’t need to decide on the ‘correct’ method names for the API making up names is hard – see the annotated .Net Framework bookBreaking these rules can cause problems GET is supposed to not cause side-effects But if this is no true on your pages, then spidering causes problemsIdempotent – has a side effect, but the side effect is well knownPOST is used to create a resource where the server needs to define the URICachability lends itself to etagging Conditional GET implies a full get ONLY if the etags have changedCan’t get the same scale using SOAP
  • Best Practices for Architecting a Pragmatic Web API.

    1. 1. Best Practices for Architecting a Pragmatic Web API Mario Cardinal Agile Coach & Software Architect www.mariocardinal.com @mario_cardinal October 15
    2. 2. Who am I? • Agile Coach & Software architect • Co-Founder of Slingboards Lab • http://mariocardinal.com
    3. 3. 3 Content 1. REST – What is it? 2. RESTful or Resource APIs? 3. Resource APIs or Web APIs? 4. Web APIs – Best practices
    4. 4. Application Programming Interface (API)  A Web API is a software intermediary that makes it possible for application programs to interact with each other and share data.  Often an implementation of REST that exposes a specific software functionality.  Simple, intuitive and consistent.  Friendly to the developer.  Explorable via HTTP tool. 4 API
    5. 5. REST – What is it?  An architectural style (extends client-server) introduced by Roy Fielding  Defines a set of constraints influenced from the architecture of the Web  URLs represent resources  Clients interact with resources via a uniform interface  Messages are self-descriptive (ContentType)  Services are stateless  Hypermedia (i.e. href tags) drive application state5
    6. 6. A more lightweight way to build services (API)  Using URLs to build on Web experience  http://myservice.com/api/resources  http://myservice.com/api/resources/{id}  http://myservice.com/api/resources/{id}/relation  HTTP verbs  GET, POST, PUT, PATCH, DELETE  Manage errors at the transport level 6
    7. 7. Uniform Interfaces (HTTP Verbs) GET POST PUT PATCH Updates an existing resource (partially) DELETE Retrieves a resource Guaranteed not to cause side-effects (SAFE) Results are cacheable Creates a new resource (process state) Unsafe: effect of this verb isn’t defined by HTTP Updates an existing resource Used for resource creation when client knows URI Can call N times, same thing will always happen (idempotent) Can call N times, same thing will always happen (idempotent) Removes a resource Can call N times, same thing will always happen (idempotent)
    8. 8. Resources come from the business domain  Task Board Sticky Notes 8
    9. 9. Resources are nouns  http://myservice.com/api/stickyNotes  Verb: GET  Action: Retrieves a list of sticky notes  http://myservice.com/api/stickyNotes/12  Verb: GET  Action: Retrieves a specific sticky note  http://myservice.com/api/stickyNotes  Verb: POST  Action: Creates a new sticky note 9
    10. 10. Resources are nouns  http://myservice.com/api/stickyNotes/12  Verb: PUT  Action: Updates sticky notes #12  http://myservice.com/api/stickyNotes/12  Verb: PATCH  Action: Partially updates sticky note #12  http://myservice.com/api/stickyNotes/12  Verb: DELETE  Action: Deletes sticky note #12 10
    11. 11. Most so-called RESTful APIs are not RESTful at all and that’s not a bad thing at all
    12. 12. Rather, most “RESTful APIs” are really “Resource APIs” http://ServiceDesignPatterns.com/WebServiceAPIStyles/ResourceAPI again, not a bad thing at all. Resource APIs totally rock !!!
    13. 13. REST Constraint Resource APIs Client/Server Yes Stateless Not required Cacheable Responses Not required (Generic) Uniform Interface Yes Unique URIs Yes Resources manipulated through Representations Yes Hypermedia as the Engine of Application State Not required Copyright © 2012 Rob Daigneau, All rights reserved
    14. 14. Stateless and cacheable response  Resource APIs allow the use of cookies  Cookies create session state that are partly store on the client (user identification) and on the server (the state).  Any response with a Set-Cookie header force the client to send the cookie in every subsequent HTTP request  Cookies interfere with cacheable response  Any response with a Set-Cookie header should not be cached, at least not the headers, since this can interfere with user identification and create security problems 14
    15. 15. Hypermedia constraint  Hypermedia as the Engine of Application State (HATEOAS)  Hypermedia constraint states that interaction with an endpoint should be defined within metadata returned with the output (URL)  Apply state transitions (at run time) by following links  Resource APIs allow URL to be known when code is written, and not discover at run time 15
    16. 16. Most so-called Web APIs are Resource APIs http://en.wikipedia.org/wiki/Web_API again, not a bad thing at all. Web APIs totally rock !!!
    17. 17. 17 Web APIs – Best practices 1. URL EndPoint  Resources  Version 2. Message Body  Content-Type 3. Error handling  HTTP Status Code 4. Security 5. Documentation
    18. 18. URL identifies a resource  Endpoint name should be plural  stickyNotes, collaborators  Do not forget relations (business domain)  GET /api/stickynotes/12/collaborators - Retrieves list of collaborators for sticky note #12  GET /api/stickynotes/12/collaborators/5 - Retrieves collaborator #5 for sticky note #12  POST /api/stickynotes/12/collaborators - Creates a new collaborator in sticky note #12  PUT /api/stickynotes/12/collaborators/5 - Updates collaborator #5 for sticky note #12 18
    19. 19. Verbs (actions) as resources  Actions that don't fit into the world of CRUD operations can be endpoint  Change state with ToDo, InProgress or Done action  Mark a sticky note in progress with PUT /stikyNotes/:id/inProgress  GitHub's API  star a gist with PUT /gists/:id/star  unstar with DELETE /gists/:id/star 19
    20. 20. Use Query to simplify resources  Keep the base resource URLs lean by implementing query parameters on top of the base URL  Result filtering, sorting & searching  GET /api/stickyNotes?q=return&state=ToDo&sort=- priority,created_at  Limiting which fields are returned by the API  GET /api/stickyNotes?fields=id,subject,state,collaborator,up dated_at&state=InProgress&sort=-updated_at 20
    21. 21. Paginate using link headers  Return a set of ready-made links so the API consumer doesn't have to construct links themselves  The right way to include pagination details today is using the ‘Link header’ introduced by RFC 5988 21 Link header: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next", <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"
    22. 22. Versioning  Version via the URL, not via headers  http://api.myservice.com/v1/stickynotes  http://myservice.com/v1/stickynotes  Benefits  Simple implementation  Ensure browser explorability  Issues  URL representing a resource is NOT stable across versions 22
    23. 23. Message (Content-type)  JavaScript Object Notation (JSON) is the preferred resource representation  It is lighter than XML but as easy for humans to read and write  No parsing is needed with JavaScript clients  Requiring Content-Type JSON  POST, PUT & PATCH requests should also require the Content-Type header be set to application/json or throw a 415 Unsupported Media Type HTTP status code 23
    24. 24. Message (Content-type)  A JSON object is an unordered set of name/value pairs  Squiggly brackets act as 'containers'  Square brackets holds arrays  Names and values are separated by a colon.  Array elements are separated by commas 24 var myJSONObject = { "web":[ { "name": "html", "years": "5" }, { "name": "css", "years": "3" }] "db":[ { "name": "sql", "years": "7" }] }
    25. 25. Message (Content-type)  camelCase for field names  Follow JavaScript naming conventions  Do not pretty print by default  Gzip by default  Gzipping provided over 60% in bandwidth savings  Always set the Accept-Encoding header 25 {“customerData" : {"id" : 123, "name" : "John" }} Header: Accept-Encoding: gzip
    26. 26. Message (Post, Put and Patch)  Updates & creation should return a resource representation  To prevent an API consumer from having to hit the API again for an updated representation, have the API return the updated (or created) representation as part of the response  In case of a POST that resulted in a creation, use a HTTP 201 status code and include a Location header that points to the URL of the new resource 26
    27. 27. HTTP caching header  Time-based (Last-Modified)  When generating a request, include a HTTP header Last-Modified  if an inbound HTTP requests contains a If- Modified-Since header, the API should return a 304 Not Modified status code instead of the output representation of the resource  Content-based (ETag)  This tag is useful when the last modified date is difficult to determine 27
    28. 28. HTTP Rate limiting header  Include the following headers (using Twitter's naming conventions as headers typically don't have mid-word capitalization):  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 28
    29. 29. HTTP status 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 29
    30. 30. HTTP status codes  400 Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error  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 isn't allowed for the authenticated user 30
    31. 31. HTTP status codes  409 Conflict - The request could not be completed due to a conflict with the current state of the resource  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 31
    32. 32. Security  Encryption  HTTPS (TLS) everywhere - all the time 32
    33. 33. Security  Authentication  Never encode authentication on the URI  Always identify the caller in the HTTP header  Each request should come with authentication credentials  Basic authentication over HTTPS 33
    34. 34. Basic authentication over HTTPS  Create a string with username and password in the form ”username:password”  Convert that string to a base64 encoded string  Prepend the word “Basic” and a space to that base64 encoded string  Set the HTTP request’s Authorization header with the resulting string 34 Header: Authorization: Basic anNtaXRoOlBvcGNvcm4=
    35. 35. Security  Autorization  Return HTTP 403 Status Code if not authorized  If necessity, use the body to provide more info 35 HTTP/1.1 403 Forbidden Content-Type: application/json; charset=utf-8 Server: Microsoft-IIS/7.0 Date: Sat, 14 Jan 2012 04:00:08 GMT Content-Length: 251 { “code" : 123, “description" : "You are not allowed to read this resource" }
    36. 36. Documentation  An API is only as good as its documentation  Docs should be easy to find  http://myservice.com/api/help  Docs should show examples of complete request/response cycles  Docs should provide error code  HTTP 4xx and 5xx Status Code  Error Code for HTTP 409 Status Code  The holy grail for Web API is an auto-generated, always up-to-date, stylish documentation 36
    37. 37. Documentation 37 URI https://mysite.com:3911/api/members/{id} HTTP verb PUT Parameters id : Card number of the member. Body name : Name of the member. email : Email adress of the member. langage : Langage used by member (Fr_CA ou En_US) Sample body { "name":"Mario Cardinal", "email":“mcardinal@mariocardinal.com", "language":"fr_CA" } Success Response Status Code: 204 No Content Error Response Status Code: 400 Bad Request, Body: {"Error Code":"..."} Status Code: 401 Unauthenticated, see WWW-Authenticate value in header Status Code: 403 Forbidden Status Code: 404 Not Found Status Code: 429 Too Many Requests, see Retry-After value in header Status Code: 500 Internal Server Error Status Code: 503 Service Unavailable Error Code 10: Inactive member 20: Denied access member 110: Database issues, Retry later
    38. 38. 38 Do not hesitate to contact me mcardinal@mariocardinal.com @mario_cardinal Q & A
    1. A particular slide catching your eye?

      Clipping is a handy way to collect important slides you want to go back to later.

    ×