"pragmatic" REST"pragmatic" definition:Dealing with things sensibly and realistically in a way that isbased on practical rather than theoretical considerations."Outside-in" approachWhat are we trying to achieve with an API?The APIs job is to make the developer as successful aspossible. The orientation for APIs is to think about designchoices from the application developers point of view.
API ~ WiFiAPIs should be like the wifi. Any device canconnect to it and use all the functionalities.What is the design with optimal benefit for the appdeveloper?
Nouns - good; verbs - badThumb rule: Keep simple things simpleSimple and intuitive base URLAffordance is a design property that communicates howsomething should be used without requiring document.There should be only 2 base URLs per resource.Example: /dogs /dogs/1234
Nouns - good; verbs - badKeep verbs out of base URLsThis will lead to: ● Long list of URLs ● No consistent patternWhich will make it difficult for developers to learn and use.
Plural & concrete nouns● Use either plural or singular names but be consistent.Ex: Foursquare: /checkins GroupOn: /deals Zappos: /product● Concrete names are better than abstractEx: API that access content in various form - blogs, videos, news articles andso on.- Abstract names: /items or /assets- Concrete names: /blogs, /videos, /newsAim for concrete naming & number of resources between 12 and 24
Simplify associationsProblemResources always have association relationships to otherresources.Ex: Get all the dogs who belong to owner 13.The relationships can be more complex which leads URLs with multi leveldepth.Ex: /resource/identifier/resource/identifier/resourceIn this case: /owner/13/dogsSolution: sweep complexity behind HTTP "?"Ex: /dogs?owner=13&color=red
Handling errors (1/5)● Web API is a black box for developer● error codes becomes a key tool to provide context and visibility to use APIsBest practices for designing error codes:● Use HTTP status codes● Make messages returned in the payload as verbose as possible
Handling errors (2/5)1. Use HTTP status code● Try and map the status codes to relevant standard- based codes● The are around 70 HTTP status codes. Use only those which are very common
Handling errors (3/5)How many status codes should we use?The are only 3 real outcomes:● Everything worked - success● The application did something wrong - client error● The API did something wrong - server error
Handling errors (4/5)Start using with few (say 3) codes and add as per therequirement. But should not be more than 8.Sample codes: ● 201 - Created ● 304 - Not Modified ● 404 - Not Found ● 403 - Forbidden ● 401 - UnauthorisedIt is important that the code that is returned is somethingthat can be consumed and acted upon by the developer.Click here to get the complete list of HTTP error codes.
Handling errors (5/5)2. Additional information in response message● Use plain language to describe the error● Link to more information page related to the error in the description is highly recommended
VersioningNever release an API without at version and make theversion mandatory.Twilio: /2010-04-01/accountsFacebook: ?v=1.0How to think about versioning?● Specify the version with a v prefix● v tag should have the highest scope: (ex: /v1/dogs)● Avoid dot notation in versions (ex: v1, v2)
PaginationSupport partial response by adding optional fields in a comma delimited listLinkedin: /people:(id,first-name,last-name,industry)Facebook: /joe.smith/friends?fields=id,name,pictureGoogle: ?fields=title,media:group(media:thumbnail)Use limit and offset to make it easy for developers to paginate objectsFacebook: offset 50 and limit 25Linkedin: start 50 and count 25Twitter: page 3 and rpp 25 (records per page)
Non resource responsesUse verbs not nouns for all the APIs that do not return aresource. For example:CalculateTranslateConvert/convert?from=EURO&to=USD&amount=100Separate out a section of documentation for all the nonresource returning requests.
Tips for searchGlobal search/search?q=foo+bar (Google approach)Scoped search/owners/5283/dogs?q=foo+barNote: Parameter q indicates a search query.
Subdomain for APIsConsolidate all API requests in a single subdomain.api.facebook.comgraph.facebook.comapi.foursquare.comapi.twitter.comstream.twitter.comsearch.twitter.com
AuthenticationRecommendation: Use the latest OAuthFacebook: OAuth 2.0Twitter: OAuth 1.0aPayPal: Permission service API
API facade pattern (1/4)Credible, relevant and differentiated
API facade pattern (2/4)Three steps approach:● Design the ideal APIDesign the URLs, request parameters and responses, payloads, headers,query parameters, and so on. The API design should be self consistent● Implement the design with data stubsUser temporary data without connecting to the internal system.● Mediate (or) integrate between the facade and the systemsOne big problem -> 3 smaller problems
API facade pattern (3/4)Focus on app developer. API should be:● Easy to use● Self-consistent● Intuitive