RESTful API Thoughts on design! 

Copyright ˅ All Right Reserved by Buzzvil What is REST? • REpresentational State Transfer (REST) is a style of architecture based on a set of principles that describe how networked resources are defined and addressed. Architectural style designed for distributed systems and, particularly, the World Wide Web Roy Fielding A PhD. dissertation at University of California-Irvine Not only HTTP Not tied to HTTP, but associated most commonly with it Constraints Not a standard, but rather a set of principles on networked resources 

Copyright ˅ All Right Reserved by Buzzvil REST Constraints • An application or architecture considered RESTful or REST-style has to meet the following constraints: • Client-server separation • Stateless • Cacheable • Layered systems • Uniform interface constraint (constraints affecting API design) • Identification of resources • Manipulation of resources • Self-descriptive messages • Hypermedia as the engine of application state 

Copyright ˅ All Right Reserved by Buzzvil • Client component that sends requests and a server component that receives requests and may issue a response • A uniform interface separates clients and servers interfaces Client-Server 

Copyright ˅ All Right Reserved by Buzzvil Stateless • Communication between client and server has to be stateless - each request should contain all the necessary data in order to make the server understand the request • Stateless adds visibility, reliability, and scalability. But incurs more network request. Message with all data needed for operation 

• Subsequent requests to the server do not have to be made if the required data is already in a local cache on the client side • Caching brings performance improvement for client side and scalability for a server because the load has reduced. Copyright ˅ All Right Reserved by Buzzvil Cacheable $ $ $ Client + Cache 

• Intermediary servers must be available to make the system more scalable. • Each component cannot "see" beyond the immediate layer with which they are interacting Copyright ˅ All Right Reserved by Buzzvil Layered System Fielding 2000 

• Information is transferred in a standardized form rather than one which is specific to an application’s needs (like SOAP). • Sub-constraints • Identification of resources - uses a resource identifier to identify the particular resource involved in an interaction between components. • Manipulation of resources - connectors provide a generic interface for accessing and manipulating the value set of a resource • Self-descriptive messages - the message consists of data and metadata describing the data • Hypermedia as the engine of application state (HATEOAS) - The client doesn’t have a built in knowledge of how to navigate and manipulate the model. Instead server provides that information dynamically Copyright ˅ All Right Reserved by Buzzvil Uniform interface 

Copyright ˅ All Right Reserved by Buzzvil RESTful API Everyday you use a browser https://www.buzzvil.com/index.html And you enter URLs to “GET” a “Resource” And webpage “resource” of a specific “media type” 

Copyright ˅ All Right Reserved by Buzzvil RESTful API It is not human accessing the resource, its software https://www.buzzvil.com/index.html And the software also want to manipulate and navigate the resource It doesn’t have to be webpage, it can be any file (media type) 

Copyright ˅ All Right Reserved by Buzzvil RESTful API • The fundamental concept in any RESTful API is the resource. • A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. (similar to object in OOP) • it can be: a document or image, a temporal service, a collection of other resources, a non-virtual object (e.g. a person), and so on • URI is used to identify the resources 

Copyright ˅ All Right Reserved by Buzzvil RESTful API • A REST API is based completely on the HTTP standard. It manipulates resource using HTTP methods. • RESTful API applies the four basic functions of persistent storage, CRUD (Create, Read, Update, Delete), to a set of resources using HTTP Methods • Create - POST - for creation of resource • Read - GET - for retrieving/reading a representation of resource • Update - PUT - update one existing resource on the server with the information contained on the request. However, PUT can also be used to create resource if it is missing. • Delete - DELETE - to delete a resource by providing its ID • Safe methods - GET • Idempotent methods - GET, PUT, DELETE 

• HATEOS - REST client hits an initial API URI and uses the server-provided links to dynamically discover available actions and access the resources it needs. • Media Type • Link Relations • Media Type - can be represented resources in several ways - JSON, XML, etc. • A client doesn’t know what a server is going to send it • A server doesn’t know what a client can handle • Content types are negotiated using headers – Client describes what it wants with Accept header – Server (and client during POST and PUT) describes what it is sending with Content-Type header Copyright ˅ All Right Reserved by Buzzvil RESTful API 

• Link Relations - A client cannot be expected to know what a resource is related to and where those relations are located • The server describes these relations as part of its payload • RFC 5988 - web linking • JSON Hypermedia API Language (HAL) • Link has two parts – rel – href • rel values are “standardized” so client can recognize them – – {“companyId”: 10, “name”: “Buzzvil”, ..“links”:[{“rel”: “products”, “href”: “10/products”, “type”: “GET”}]} Copyright ˅ All Right Reserved by Buzzvil RESTful API 

Copyright ˅ All Right Reserved by Buzzvil RESTful API • Client-Server • Servers and clients may be replaced and developed independently, as long as the interface between them is not altered. • A client should know only resource URIs and that’s all. • Stateless • No client context shall be stored on the server between requests. The client is responsible for managing the state of the application. • Every HTTP request happens in complete isolation. • Advantages: Scaling API by concurrency, less complex, easy to cache 

Copyright ˅ All Right Reserved by Buzzvil RESTful API • Cacheable • Using HTTP headers, an origin server indicates whether a response can be cached • e.g. Expires, Cache-Control, ETag, Last-Modified • Layered System • We can use a layer system architecture where we deploy the APIs on Server A, and store data on Server B and authenticate request in Server C 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Better explained by example • Identify objects which will be presented as resources • Consider: Devices and Configurations • Configuration is a sub-resource of Device • Create resource URIs • focus on the relationship between resources and its sub-resources. 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Determine resource representation • XML or JSON • Collection of Device Resource • /devices • To keep the payload size small, include only important information about the resource 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Single Device Resource • /devices/12345 • Complete information of a device • Include a list of links for sub- resources and other supported operations. • This will make the API HATEOAS driven 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Collection of Configuration Resource • /configurations • Single Configuration Resource • /configurations/42342 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Collection of Configuration Resource Under a Device • /device/12345/ configurations • Single Configuration Resource Under a Device • /device/12345/ configurations/11223344 

Copyright ˅ All Right Reserved by Buzzvil Design RESTful API • Assigning HTTP Method • Browse all devices or configurations • GET /devices • GET /devices/1234/configurations • Create device or configuration resource • POST /devices • POST /configurations • Update device or configuration resource • PUT /devices/1234/configurations/678678 • Delete devices or configurations resource • DELETE /devices/1234 

Thank you! Copyright ˅ All Right Reserved by Buzzvil 

Copyright ˅ All Right Reserved by Buzzvil References • Fielding’s Dissertation - https://www.ics.uci.edu/~fielding/pubs/dissertation/ rest_arch_style.htm#sec_5_1 • Rest API must be hypertext-driven - http://roy.gbiv.com/untangled/2008/rest-apis- must-be-hypertext-driven • Tutorial link - https://restfulapi.net/rest-api-design-tutorial-with-example/