![An Introduction to ReSTful APIs 7
{
"translatedText": "Mein Name ist Jeff"
}
]
}
}
It is interesting to note that the information returned from the server contains absolutely no
instructions for how the data is to be rendered, which is one of the six constraints described in
table 1. The web page’s coding interprets the data returned and displays the information. In
keeping with the statelessness of a ReSTful API, once the server has returned the request, it no
longer has any knowledge of the existence of the client until another request is made. The client
has the option to cache the information to be used again later. The information being requested
and returned uses a uniform interface that has been designed by Google and the creators of the
application that uses the API have agreed to send the request in the format that Google requires.
The application can use the constraint of code on demand to manipulate the data to be used in a
manner that is most useful to the users of the application. In our example of the request to
Google Translate we also see some of the six data elements that were defined earlier: The target
is: “Hello World My Name is Jeff” text to be translated from one language to another, the
resource identifier www.googleapis.com/language/translate, and the control data that identifies
this as a GET message type.
Here is another simple example of a request for a resource: GET http://www.thomas-
bayer.com/sqlrest/CUSTOMER/3/. Information about customer number three has been requested](https://image.slidesharecdn.com/83637200-c8a3-4822-917b-83d81e085ba3-160314061336/85/ReSTful-API-Final-7-320.jpg)
ReSTful API Final
- 1. Claudine Bruyns Dr. Jiang Li CSCI 4800 February 27, 2015 An Introduction to ReSTful APIs In 2000 Roy Fielding introduced the idea behind ReSTful APIs in his dissertation Architectural Styles and the Design of Network-based Software Architectures. Since that time ReST has become one of the dominant frameworks for sending a request from client to server to interact with data and have a response returned to the client in a format that the client can utilize. This is accomplished through ReST using the well-established HTTP (Hyper Text Transfer Protocols.) The idea of a ReSTful API is difficult to grasp, because it is not something you can hold in your hand, but it is more of a set of best practices for using APIs. In order to understand what ReSTful APIs are, how they are created, and their usefulness, it is important to define the terms associated with ReST. The acronym ReST stands for Representational State Transfer. An API is an Application Programming Interface; in the context of HTTP it is a way to share data across various applications. ReST uses the four HTTP actions of create, read, update and delete also known as CRUD. These are implemented using the methods GET, POST, PUT and DELETE. ReST provides a standardized way to communicate that also allows the developer of the API to utilize the network resources efficiently. ReSTful defines how a client and server will exchange and represent information about resources. A resource is a piece of information that can be named and a unique link created to identify its location by using URLs. The architecture also defines that the interface be stateless meaning that the server does not store information about the state of the client. Finally the design
- 2. An Introduction to ReSTful APIs 2 defines a standard way of using the well-established HTTP actions known as CRUD; create, read, update, and delete. The actions are executed using GET, POST, PUT, and DELETE. Fielding describes three fundamental ReST components: constraints, elements, and connectors. The constraints provide a framework for the implementation of the API. Each of the six constraints has pros and cons. The following table lists the constraints with a brief description, and the advantage and disadvantage of each. Table 1. ReST Constraints Constraint name Description Advantage(s) Disadvantage(s) Client/Server This constraint provides for the separation of the data storage from the user interface. Must be Stateless The session state resides entirely on the client; the server should store no session data. Reliability, visibility and scalability. Decreases network performance and data transfer is repetitive. Cacheable Allows data to be stored with the option for the client to refuse the data later. Improves network performance by reducing repetitive data transfers. Data may become stale. Uniform Interface Standardizes the form of the information transferred. Conforms to the architectural principles of generality and simplicity. Specifically designed for Hypermedia. May not be as efficient as other forms of data transfer. Layered Encapsulates Data Provides for protection of the data by allowing security policies to be enforced. Can increase system latency. Code-On-Demand This constraint is optional and allows for extended Allows scripts or applets to be used on the client side for May not be permitted by organizations due to
- 3. An Introduction to ReSTful APIs 3 functionality of the API. processing some data. firewall rules. Source: Fielding, Roy. "Architectural Styles and the Design of Network-based Software Architectures." (2000). ReST also has six data elements that are used for the request and response for access to information. 1) The resource – is the target of the hypertext reference. The resources are data that can be named such as documents, images, services, etc. 2) The resource identifier – the link or reference to the resource such as the URL an example would be http://apsu.edu. 3) Representations – the data types associated with the resource; HTML documents and JPEG images. 4) Representation metadata. 5) Resource metadata – are the attributes that help define the resource. 6) Control data – identifies the purpose of the message. Finally there are the connectors. Client connectors initiate the communication by making a request. Server connectors listen for and respond to the client request. Cache connectors save responses to be used later. Resolver connectors translate the resource identifiers into network addresses. Tunnel connectors allow clients to communicate directly with the server. In their book Restful Java Web Services: Master Core REST Concepts And Create Restful Web Services In Java, Sandoval, Roussev and Wallace describe ReST like this: “In their simplest form, ReSTful web services are networked applications that manipulate the state of resources. In this context, resource manipulation means resource creation, retrieval, update, and deletion. However, ReSTful web services are not limited to just these four basic data manipulation concepts.” The process of transmitting data using a ReSTful API starts with the client sending a request GET, POST, PUT, or DELETE data for a resource through a URI. Included in the request the client specifies what kind of representation it can receive in the Accept Request Header Field.
- 4. An Introduction to ReSTful APIs 4 The server receives and interprets the request, then passes the data on to the ReSTful framework. The server searches for the resource that was requested. Once the data is located the server packages the data into the representation the client requested. Usually the representation will either be XML (eXtensible Markup Language; according to the w3schools.com, was designed to describe data with a focus on what data is. XML is both human and machine-readable. XML tags are created by the author of the XML document to describe the data inside the tags.) or JSON (JavaScript Object Notation; according to json.org “is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate.”) Along with the requested data an HTTP response code is sent to identify the status of the request. From the REST API Tutorial web site www.restapitutorial.com/httpstatuscodes.html the most frequent response codes are: 1xx Informational only: 100 Continue 2xx Success: 200 OK, 201 Created 3xx Redirection: 304 Not Modified 4xx Client Error: 400 Bad Request, 404 Not found. 5xx Server Error: 500 Internal Server Error (Code problem) Included in the packet generated when a client makes a request through a ReSTful API, are the methods that provide instructions to the server. These instructions are called annotations in the Java EE application and are described in more detail by Oracle in their Java EE Tutorial. The main methods used are: @PATH – The relative URI where the resource data is hosted @GET – The request method for retrieving data about a resource (this method should only be used to read data.)
- 5. An Introduction to ReSTful APIs 5 @POST – Submits data for the server to process (this method is used to change data.) @PUT – This method requests that data be inserted @DELETE – This method as the name suggests is a request to remove a resource One thing to take note of with the methods for manipulating data is that the designer of the client must ensure that the actions do not violate the property of idempotent. Meaning there should be no side effects to making the same request multiple times. A client should be able to make the same GET request for a resource multiple times and the returned data should be identical each time. The format for requesting a resource through an API is done using a profile. A developer does not necessarily need to create a brand new profile each time the want to offer or use and API. There are already many different profiles that have been developed for various types of API calls. AtomPub is used for publishing and editing web resources, used extensively in WordPress sites. Collection+JSON is used to manage and query simple collections. hCard microformat is built upon the familiar vCard that captured data normally found on business cards. There are two parts to creating a ReSTful API. First, the design of the server and database must be done in such a way that the resources may be easily and securely accessed. In addition server has the responsibility of protecting the data against malicious requests. The server also has to be able to respond with multiple representations of the resource to ensure that the client will be able to display the information properly. Second, the client will need to be designed to make proper requests for the access of the resource. This includes using the GET, POST, PUT, and DELETE actions safely. ReSTful APIs allow the efficient exchange of data using a standard
- 6. An Introduction to ReSTful APIs 6 architecture for the request and return of resources through a previously agreed upon format for the interface. Now that we know the architecture of a ReSTful API and what HTTP building blocks create an API; what can we do with a ReSTful API? Fundamentally an API allows two unrelated system to exchange information. There are many web applications that utilize ReSTful APIs, Google Translate being one of the most familiar, https://cloud.google.com/translate/v2/using_rest. Below is an example of what a GET request API from a client to Google Translate would look like: GET https://www.googleapis.com/language/translate/v2?key=INSERT-YOUR- KEY&source=en&target=de&q=Hello%20world&q=My%20name%20is%20Jeff The first thing to notice is that the method is GET followed by the link to the resource. Now that the request is made the server will send back to the client a representation to be displayed in the browser. Google Translate is using a JSON standard for the response and it is sent to the client in the following format: 200 OK { "data": { "translations": [ { "translatedText": "Hallo Welt" },
- 7. An Introduction to ReSTful APIs 7 { "translatedText": "Mein Name ist Jeff" } ] } } It is interesting to note that the information returned from the server contains absolutely no instructions for how the data is to be rendered, which is one of the six constraints described in table 1. The web page’s coding interprets the data returned and displays the information. In keeping with the statelessness of a ReSTful API, once the server has returned the request, it no longer has any knowledge of the existence of the client until another request is made. The client has the option to cache the information to be used again later. The information being requested and returned uses a uniform interface that has been designed by Google and the creators of the application that uses the API have agreed to send the request in the format that Google requires. The application can use the constraint of code on demand to manipulate the data to be used in a manner that is most useful to the users of the application. In our example of the request to Google Translate we also see some of the six data elements that were defined earlier: The target is: “Hello World My Name is Jeff” text to be translated from one language to another, the resource identifier www.googleapis.com/language/translate, and the control data that identifies this as a GET message type. Here is another simple example of a request for a resource: GET http://www.thomas- bayer.com/sqlrest/CUSTOMER/3/. Information about customer number three has been requested
- 8. An Introduction to ReSTful APIs 8 using the format prescribed by the holder of the information. The information returned is in an XML format to be rendered in the format dictated by the requesting application as you can see below. <CUSTOMER xmlns:xlink="http://www.w3.org/1999/xlink"> <ID>3</ID> <FIRSTNAME>Michael</FIRSTNAME> <LASTNAME>Clancy</LASTNAME> <STREET>542 Upland Pl.</STREET> <CITY>San Francisco</CITY> </CUSTOMER> With this example you can see even more clearly how the returned information can be easily manipulated with Java or any other suitable programming language. This is where the constraint of code on demand may be utilized. One of the facets of ReSTful API’s that adds to its popularity is the ability for a client to delete, create or modify and entry. Banking, healthcare and even social media (such as Twitter and Facebook) utilize this characteristic. Healthcare is a great example of how two systems can use APIs. An electronic medical records (EMR) software company does not have to recreate the wheel to when they want to incorporate the ability to order medications and have interaction screenings performed to prevent medication complications. There are companies who have already created a system to screen for adverse reactions and interactions with other medications, foods and diseases. The EMR and pharmacy application companies can work together through the use of APIs. The pharmacy application, will provide the EMR vendor with the specifications for accessing their data. The EMR company will send requests for resources and in turn will
- 9. An Introduction to ReSTful APIs 9 receive a response that can then be used to complete transaction. Because of the existence of APIs the two companies can focus on what each does best. The companies who created the EMR can keep their focus on what the doctors need to see on their screen, while the pharmacy application company can focus on keeping their application up to date with new medications and regulations. There are more than 8,000 APIs currently available for use. You can find a comprehensive listing of APIs at http://www.programmableweb.com/apis/directory. The web site also has a listing of those APIs that are ReSTful. Everyday you are likely using a ReSTful API. You will find them residing on applications on your smart phone, software on your workstation at your job, a visit to your local hospital or doctors office where they use an electronic medical record, and even at home while you are interacting on the web with social media or checking your bank account balance. The ability to request data and receive the information efficiently and it in a format that can be easily manipulated and rendered by the client makes ReSTful APIs a mainstay in today’s data driven world.
- 10. An Introduction to ReSTful APIs 10 Works Cited Fielding, Ray T. "Architectural Styles and He Design of Network-based Software Architectures." Diss. U of California, Irvine, 2000. Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST). 2000. Web. 7 Feb. 2015. Sandoval, José, Atanas Roussev, and Richard Wallace. Restful Java Web Services: Master Core REST Concepts And Create Restful Web Services In Java. Birmingham, UK: Packt Publishing, 2009.eBook Collection (EBSCOhost). Web. 8 Feb. 2015. "Introduction to XML." XML Introduction. Web. 28 Feb. 2015. <http://www.w3schools.com/xml/xml_whatis.asp>. "Introducing JSON." JSON. Web. 28 Feb. 2015. <http://json.org/>. "HTTP Status Codes." HTTP Status Codes. Web. 28 Feb. 2015. <http://www.restapitutorial.com/httpstatuscodes.html>. "Java EE Tutorial." Web. 28 Feb. 2015. <http://docs.oracle.com/javaee/6/tutorial/doc/javaeetutorial6.pdf>. "Using REST." Google Developers. Web. 1 Mar. 2015. <https://cloud.google.com/translate/v2/using_rest>.