WHITE PAPER BEST PRACTICES FOR BUILDING RESTFUL WEB SERVICES Introduction Representational State Transfer (REST) is In many ways, the World Wide Web REST is not a standard in itself but instead an architectural style for designing loosely itself, which is based on HTTP, is the best is an architectural style that uses standards coupled web services. It is mainly used to example of REST-based architecture. like HTTP, XML / HTML / JSON / GIF develop lightweight, fast, scalable, and (Representations of Resources), text / html, RESTful applications use HTTP requests easy to maintain, web services that often text / xml, and image / jpeg (MIME Types). to post data (create / update), read data use HTTP as the means of communication. This is why you will never see organizations (making queries), and delete data. Hence, selling REST-based toolkits. REST uses HTTP for all four CRUD (Create / We should design REST web-services in a REST is an architectural style, Read / Update / Delete) operations. which provides direction for way that results in loosely coupled web building distributed and loosely REST defines the Web as a distributed services, which follow web standards. coupled services hypermedia (hyperlinks within It should also be development-friendly hypertext) application, whose linked and flexible enough to be used for a variety REST is not linked to any resources communicate by exchanging of new applications. particular platform or representations of the resource state. The technology – it’s an idea to In this paper, we will mainly focus on the REST architectural style provides guiding develop services to function best practices in REST, and share some similar to the Web principles for building distributed and quick tips, which can be used for REST web loosely coupled applications. services design. The difference between a web service and a website is about who accesses it. The latter is accessed by human beings and former is accessed by programmed clients External Document © 2018 Infosys Limited External Document © 2018 Infosys Limited REST Vs SOAP: When to choose REST? Simple Object Access Protocol (SOAP) • SOAP uses only XML for messages. extensions and changes can be made depends primarily on XML to provide REST supports different formats easily. The SOAP client however, is tightly coupled with the server and the messaging services. SOAP uses different • REST messages are smaller in size protocols for communication, such as integration would break if a change is and consume lesser bandwidth HTTP, SMTP, or FTP. made at either end. • REST is better in terms of performance REST should be chosen when you have REST on the other hand, is an architectural with better caching support to develop a highly secure and complex style, which uses existing HTTP actions • No third party tool is required to access API, which supports different protocols. and methods; and does not create any REST web services. Also with REST- Although SOAP may be a good choice, new standards. SOAP on the other hand, based services, learning is easier when REST may be better when you have to is a protocol. compared to SOAP develop lightweight APIs with great • There is less coupling between REST REST is more flexible compared to SOAP performance and support for CRUD Clients (browsers) and Servers; feature- operations. web services. It has the following benefits over SOAP: <Emp> http://service.com/emp/123 <Name>ABC</Name> <Id>321</Id> http://service.com/emp/{id} <Email> [email protected]</Email> http://service.com/emp? Id=1 <Org>Infosys</Org> </Emp> Resource (Nouns) Representation (XML, JSON) REST API { Name: ABC", Id: 21, Verbs GET http://service.com/emp/123 HTTP/1.1 Email: [email protected]", “Org: Infosys" (GET, PUT, POST http://service.com/emp/123 HTTP/1.1 } POST) DELETE http://service.com/emp/123 HTTP/1.1 External Document © 2018 Infosys Limited External Document © 2018 Infosys Limited REST is like a three-wheeler that rests on Resources, Representation, and Verbs Resources but HTTP verbs only tell you which action understanding, use nouns for every needs to performed on the host. There are resource. Additionally, do not mix up Resources are the fundamental elements many actions that a client can trigger on singular and plural nouns, and always use of the web platform. While working the host. plural nouns for consistency: on REST, the first task is to identify the These verbs are – resources and find out how they are linked GET parts/1 with each other. Every resource has a • GET: retrieve an existing resource GET orders/123 unique identifier on the web platform, • POST: create a new entry of resource GET seats?id=3 which is known as the universal resource • PUT: modify an existing resource identifier (URI) and the best example on • DELETE: remove an existing resource How to handle asynchronous tasks the Web is a uniform resource locator (URL). The Hypertext Transfer Protocol (HTTP) is a There is no limit on the number of URIs that Representation synchronous and stateless protocol. can refer to a resource. For example we can The third and final wheel is about The server and client get to know each access a particular domain page (of course, other during the current request. After determining a way to showcase these a resource) using http://yahoo.com and this, both of them forget about the resources to clients. REST supports all http://www.yahoo.com. request. Because of this behavior, retaining formats without any restrictions; so you information between requests is not In REST web services, we use nouns to can use any format for representing the possible at the client and server-side. identify a type of resource. Employee resources. information from EmpDB can be accessed For asynchronous requests (that take too Based on the client’s and server’s ability using the below long to complete) follow the steps detailed to work with the formats, you can go with URL:http://EmployeeService/Employee/1 below – JSON, XML, or any other format. • Place a GET / Post request which takes Verb too long to complete Verb is an HTTP action like POST, GET PUT, • Create a new task and return status DELETE, OPTIONS, etc. Best Practices code 202 with a representation of the Let’s first revisit the HTTP Request. Here we come up with a few new resource so the client can track the status of the asynchronous task Example of a GET Request: recommendations / best practices that can be used to develop flexible, easy-to-use, • On completion of the request, return response code 303 and a location GET http://www.w3schools.com/ : HTTP/1.1 and loosely coupled REST APIs. header containing a URI of resource that Status: HTTP/1.1 200 OK Accept text/xml,text/html; Use nouns for Resources displayed the result set Accept-Encoding gzip, deflate, sdch and not verbs • On request failure, return response code Accept-Language en-US,en; 200 (OK) with a representation of the Verbs should not be used for resources task resource informing that the process because doing this will give a huge list Using URLs, the identity of the target server has failed. Clients will look at the body of URLs with no pattern – which makes can be determined for communication, to find the reason for the failure. maintenance very difficult. For easy Here, an example is provided for a file- upload web service, which supports asynchronous model. Url + Verb Let’s start with the client submitting a POST request to initiate a multi file upload task: Status Code + Response # Request POST /files/ HTTP/1.1 Host: www.service.com Server External Document © 2018 Infosys Limited External Document © 2018 Infosys Limited A response is received, which reflects that For the Amazon customer page, check IANA website. Designing resource the process has started. Response code 202 you can design a “Customer View” representations is also very important as indicates that the server has accepted the composite resource that aggregates all it defines the relationships between the request for processing: the information and presents it to the resources. customer. An example of this is XML is the most commonly used format # Response provided below: HTTP/1.1 202 Accepted across the applications. On the other hand, Content-Type: JSON (JavaScript Object Notation) is very # Request application/xml;charset=UTF-8 popular across browsers as it is easier to Content-Location: GET /amazon/customer/0004532/ consume, because it is based on JavaScript http://www.example.org/files/1 view HTTP/1.1 Host: www.amazon.com <status> Be flexible while choosing the variety <state>pending</state> <message xml:lang=”en”> # Response of media types and formats, because File Upload process is started HTTP/1.1 200 OK we need multiple formats for some and to get status refresh page Content-Type: application/xml representations. For instance, managing after sometime. <view> parts of automobiles need the following </message> <customer> representations: </status> <id>0004532</id> <atom:link rel=”self” • HTML pages to describe the parts The client can check the status by passing href=”www.amazon.com/ customer/0004532”> • XML-formatted representation a GET request, but if the server is still <name>ABCD</name> for each part processing the file upload, it will return the <dob>25th July</dob> • Parts specification in PDF format same response. </customer> <orders> • An Atom feed of all the new parts Once the server successfully completes <atom:link href= the file upload process, it redirects the ”www.amazon.com/ Error Handling customer/0004532/orders” /> client to the new page. The response code <order> When a server shows some error 303 states that the result exists at the URI <id>...</id> because of problems within the server, available in the location header: ..