Introduction to ReSTful Web APIs [FOSSMeet '16@NIT-C]

Building restful web services, like other programming skills is part art, part science. Through this talk, I aim to give an idea about ReST APIs and discuss some best practices while designing it. The session will begin with an introduction to APIs in general. After that, the idea of ReST API is discussed in detail along with the concepts of resources,HTTP verbs and status codes. Finally, will explore some best practices while designing ReST APIs.

Transcript

1. Introduction to ReSTful WEB APIs FOSSMeet ‘16
2. SHAHUL HAMEED Python Evangelist Open Source Enthusiast
3. Contents ➔ Introduction ➔ Why we need this? ➔ ReST, API and ReSTful web API ➔ How it works? ➔ Best practices
4. Web Applications In computing, a web application or web app is a client-server software application in which the client (or user interface) runs in a web browser.
5. Some scenarios ... • Photos can be shared from sites like Flickr and Photobucket to social network sites like Facebook and MySpace. • Content can be embedded, e.g. embedding a presentation from SlideShare on a LinkedIn profiles. • Content can be dynamically posted. Sharing live comments made on Twitter with a Facebook account, for example, is enabled by their APIs. • Video content can be embedded on sites served by another host. • User information can be shared from web communities to outside applications, delivering new functionality to the web community that shares its user data (Facebook / Google Login)
6. Not just that ..
8. ReST is short for representational state transfer, is a set of constraints that ensure a scalable, fault-tolerant and easily extendible system. The world-wide-web is an example of such system (and the biggest example, one might say). REST by itself is not a new invention, but it's the documentation on such systems like the world-wide-web.
9. Web API A server-side web API is a programmatic interface consisting of one or more publicly exposed endpoints to a defined request-response message system, typically expressed in JSON or XML, which is exposed via the web.
10. ReSTful API To be ReSTful, an API must comply with the six constraints of REST, which are : Client-Server, Stateless, Cacheable, Uniform Interface , Layered System & Code-On-Demand.
11. Key Concepts ➔ Resources ➔ URLs ( Uniform Resource Locators) ➔ HTTP - methods and response codes
12. Resources & URLs A resource is an object with a type and associated data. Each resource is identified by a URL. For e.g, in an e-commerce application, users, orders etc. are resources. /users /users/5 /users/5/orders /users/5/orders/42 /users/5/orders?processed=true /users/5/orders?processed=true&page=1
13. HTTP Verbs GET - Read a specific resource (by an identifier). POST - Create a resource PUT - Update a specific resource (by an identifier). Can also be used to create a specific resource if the resource identifier is known before-hand. DELETE - Remove/delete a specific resource by an identifier.
14. Example GET /tickets - Retrieves a list of tickets GET /tickets/12 - Retrieves a specific ticket POST /tickets - Creates a new ticket PUT /tickets/12 - Updates ticket #12 DELETE /tickets/12 - Deletes ticket #12
15. READ $ curl -XGET http://api.fossmeet.com/v1/users HTTP/1.1 200 OK Content-Type: application/json { "users":[] }
16. WRITE $ curl -XPOST http://api.fossmeet.com/v1/users -d “name=Arun” HTTP/1.1 201 CREATED Content-Type: application/json Location : http://api.fossmeet.com/v1/users/1 { }
17. $ curl -XGET http://api.fossmeet.com/v1/users/1 HTTP/1.1 200 OK Content-Type: application/json { “name” : “Arun”, “links” : { “orders” : “http://api.fossmeet.com/v1/users/1/orders/” “self” : “http://api.fossmeet.com/v1/users/1” }}
18. UPDATE $ curl -XPUT http://api.fossmeet.com/v1/users/1 -d “name=Anu” HTTP/1.1 200 OK
19. $ curl -XDELETE http://api.fossmeet.com/v1/users/1 HTTP/1.1 204 No Content DELETE
20. Tips and Best Practices ➔ Appropriate resource names provide context for a service request, increasing understandability of the API. ➔ Choose resources wisely, some examples include • Users of the system. • Courses in which a student is enrolled. Use identifiers in your URLs instead of in the query-string. Using URL query-string parameters is fantastic for filtering, but not for resource names. Good: /users/12345 Poor: /api?type=user&id=23
21. ➔ Resource names should be nouns. Avoid verbs as resource names, to improve clarity. Use the HTTP methods to specify the verb portion of the request. ➔ Avoid using collection verbiage in URLs. For example 'customer_list' as a resource. Use pluralization to indicate the collection metaphor (e.g. customers vs. customer_list). ➔ Use lower-case in URL segments, separating words with underscores ('_') or hyphens ('-'). Some servers ignore case so it's best to be clear. ➔ Version your API in URLs. ➔ Use HTTP Response Codes to Indicate Status
22. Commonly used response codes 200 OK - General success status code. This is the most common code. Used to indicate success. 201 CREATED - Successful creation occurred (via either POST or PUT). Set the Location header to contain a link to the newly-created resource (on POST). Response body content may or may not be present. 204 NO CONTENT - Indicates success but nothing is in the response body, often used for DELETE and PUT operations. 400 BAD REQUEST - General error for when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.
23. 401 UNAUTHORIZED - Error code response for missing or invalid authentication token. 403 FORBIDDEN - Error code for when the user is not authorized to perform the operation or the resource is unavailable for some reason (e.g. time constraints, etc.). 404 NOT FOUND - Used when the requested resource is not found, whether it doesn't exist or if there was a 401 or 403 that, for security reasons, the service wants to mask. 500 INTERNAL SERVER ERROR - Never return this intentionally. The general catch- all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end.
24. Read more ! ➔ http://jsonapi.org/ ➔ restful-api-design.readthedocs.org ➔ http://restcookbook.com
25. Thanks! @beingshahul +91-9495379530 shahul@computer.org www.shahul.in