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>.