RESTful Web services

Message-oriented middleware (MOM) lets a service's consumers physically and temporally decouple from the service providers. Communication between service providers and their consumers is asynchronous, and they don't need to be available at the same time because they communicate by sending and receiving messages from designated message queues. In contrast, RPC is a synchronous method of requesting remote service execution. Consumers must suspend service execution until they receive a reply from the provider.

MOM and RPC have advantages and disadvantages. MOM solutions tend to be more robust to failures than RPC, and they allow service requesters to continue to process while service providers work on their requests. However, programming MOM-based applications is more cumbersome because distribution isn't as transparent to the programmer as with RPCs. In this column, I provide a quantitative framework you can use to compare MOM- and RPC-based solutions.

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. It is similar to an object instance in an object-oriented programming language, with the important difference that only a few standard methods are defined for the resource (corresponding to the standard HTTP GET, POST, PUT and DELETE methods), while an object instance typically has many methods.

Resources can be grouped into collections. Each collection is homogeneous so that it contains only one type of resource, and unordered. Resources can also exist outside any collection. In this case, we refer to these resources as singleton resources. Collections are themselves resources as well.

Collections can exist globally, at the top level of an API, but can also be contained inside a single resource. In the latter case, we refer to these collections as sub-collections. Sub-collections are usually used to express some kind of “contained in” relationship. We go into more detail on this in Relationships.

The diagram below illustrates the key concepts in a RESTful API.

We call information that describes available resources types, their behavior, and their relationships the resource model of an API. The resource model can be viewed as the RESTful mapping of the application data model.

Resource Data

Resources have data associated with them. The richness of data that can be associated with a resource is part of the resource model for an API. It defines for example the available data types and their behavior.

Based on my experience, I have developed a strong conviction that the JSON data model has just the right “richness” so that it is an ideal data model for RESTful resources. I would recommend that everybody use it.

In JSON, just three types of data exist:

scalar (number, string, boolean, null).

array

object

Scalar types have just a single value. Arrays contain an ordered list of values of arbitrary type. Objects consist of a unordered set of key:value pairs (also called attributes, not to be confused with XML attributes), where the key is a string and the value can have an arbitrary type. For more detailed information on JSON, see the JSON web site.

Why the strong preference for JSON? In my view, JSON has the right balance between expressiveness, and broad availability. The three types of data (scalars, arrays and objects) are powerful enough to describe in a natural way virtually all the data that you might want to expose as resource, and at the same time these types are minimal enough so that almost any modern language has built-in support for them.

XML would be the other obvious contender. Actually, in the final incarnation of the RHEV-M API, XML is used to describe resources, via an XMLSchema definition. With hindsight, I believe that the XML data model is a bad choice for a RESTful API. On one side, it is too rich, and on the other side, it lacks features. XML, as an SGML off-shoot, is in my view great for representing structured documents, but not for representing structured data.

Features of XML that are too rich include:

Attributes vs elements. An XML element can have both attributes as well as sub-elements. A data item associated with a resource could be encoded in either one, and it would not be clear beforehand which one a client or a server should use.

Relevance of order. The order between child-elements is relevant in XML. It is not natural in my view for object attributes to have ordering.

The limitations of the XML data model are:

1. Lack of types. Elements in XML documents do not have types, and in order to use types, one would have to use e.g. XMLSchema. XMLSchema unfortunately is a strong contender for the most convoluted specification ever written.

2. Lack of lists. XML cannot natively express lists. This can lead to issues whereby it is not clear whether a certain element is supposed to be a list or an object, and where that element ends up being both.

REST Metadata

In addition to exposing application data, resources also include other information that is specific to the RESTful API. Such information includes URLs and relationships.

The following table lists generic attributes that are defined and have a specific meaning on all resources. They should not be used for mapping application model attributes.

Representations¶

Now that you understand resources, I want to think about representations. Suppose a client makes a GET request to /programmers/Namespacinator and gets back this JSON response:

{

    "nickname": "Namespacinator",

    "powerLevel": 5

}

That’s the programmer resource, right? Wrong! No!

This is just a representation of the programmer resource. It happens to be in JSON, but the server could have represented the programmer in other ways, like in XML, HTML or even in JSON with a different format.

The same applies when a client sends a request that contains programmer data:

POST /api/programmers HTTP/1.1

Host: CodeBattles.io

Authorization: Bearer b2gG66D1Tx6d89f3bM6oacHLPSz55j19DEC83x3GkY

Content-Type: application/json

{

    "nickname": "Namespacinator"

}

The client doesn’t send a programmer resource, it just sends a representation. The server’s job is to interpret this representation and update the resource.

Representation State¶

This is exactly how browsing the web works. An HTML page is not a resource, it’s just one representation. And when we submit a form, we’re just sending a different representation back to the server

One resource could have many representations. Heck, you could get crazy and have an API where you’re able to request the XML, JSON or HTML representations of any resource. We’re just crazy enough that we’ll do some of that.

A representation is a machine readable explanation of the current state of a resource.

Yes, I said the current “state” of the resource, and that’s another important and confusing term. What REST calls state, you probably think of as simply the “data” of a resource. When the client makes a GET request to /programmer/Namespacinator, the JSON is a representation of its current state, or current data. And if the client makes a request to update that programmer, the client is said to be sending a representation in order to update the “state” of the resource.

In REST-speak, a client and server exchange representations of a resource, which reflect its current state or its desired state. REST, or Representational state transfer, is a way for two machines to transfer the state of a resource via representations.

I know I know. We just took an easy idea and made it insane! But if you can understand this way of thinking, a lot of what you read about REST will start to make sense.

REST Architectural Constraints

REST stands for Representational State Transfer, a term coined by Roy Fielding in 2000. It is an architecture style for designing loosely coupled applications over HTTP, that is often used in the development of web services. REST does not enforce any rule regarding how it should be implemented at lower level, it just put high level design guidelines and leave you to think of your own implementation.

In my last employment, I designed RESTful APIs for telecom major company for 2 good years. In this post, I will be sharing my thoughts apart from normal design practices. You may not agree with me on a few points, and that’s perfectly OK. I will be happy to discuss anything from you with an open mind.

Let’s start with standard design specific stuff to clear what ‘Roy Fielding’ wants us to build. Then we will discuss my stuff which will be more towards finer points while you design your RESTful APIs.

Architectural Constraints

REST defines 6 architectural constraints which make any web service – a true RESTful API.

• Uniform interface
• Client–server
• Stateless
• Cacheable
• Layered system
• Code on demand (optional)

Uniform interface

As the constraint name itself applies, you MUST decide APIs interface for resources inside the system which are exposed to API consumers and follow religiously. A resource in the system should have only one logical URI and that should provide a way to fetch related or additional data. It’s always better to synonymise a resource with a web page.

Any single resource should not be too large and contain each and everything in its representation. Whenever relevant, a resource should contain links (HATEOAS) pointing to relative URIs to fetch related information.

Also, the resource representations across system should follow certain guidelines such as naming conventions, link formats or data format (xml or/and json).

All resources should be accessible through a common approach such as HTTP GET and similarly modified using a consistent approach.

Once a developer becomes familiar with one of your API, he should be able to follow the similar approach for other APIs.

Client–server

This essentially means that client application and server application MUST be able to evolve separately without any dependency on each other. A client should know only resource URIs and that’s all. Today, this is normal practice in web development so nothing fancy is required from your side. Keep it simple.

Servers and clients may also be replaced and developed independently, as long as the interface between them is not altered.

Stateless

Roy fielding got inspiration from HTTP, so it reflects in this constraint. Make all client-server interaction stateless. Server will not store anything about latest HTTP request client made. It will treat each and every request as new. No session, no history.

If client application needs to be a stateful application for the end user, where user logs in once and do other authorized operations thereafter, then each request from the client should contain all the information necessary to service the request – including authentication and authorization details.

No client context shall be stored on the server between requests. The client is responsible for managing the state of the application.

Cacheable

In today’s world, caching of data and responses is of utmost important wherever they are applicable/possible. The webpage you are reading here is also a cached version of the HTML page. Caching brings performance improvement for client side, and better scope for scalability for a server because the load has reduced.

In REST, caching shall be applied to resources when applicable and then these resources MUST declare themselves cacheable. Caching can be implemented on the server or client side.

Well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance.

Layered system

REST allows you to use a layered system architecture where you deploy the APIs on server A, and store data on server B and authenticate requests in Server C, for example. A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.

Code on demand (optional)

Well, this constraint is optional. Most of the time you will be sending the static representations of resources in form of XML or JSON. But when you need to, you are free to return executable code to support a part of your application e.g. clients may call your API to get a UI widget rendering code. It is permitted.

All above constraints help you build a truly RESTful API and you should follow them. Still, at times you may find yourself violating one or two constraints. Do not worry, you are still making a RESTful API – but not “truly RESTful”.

RESTful API

A RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.

A RESTful API -- also referred to as a RESTful web service -- is based on representational state transfer (REST) technology, an architectural style and approach to communications often used in web services development.

REST technology is generally preferred to the more robust Simple Object Access Protocol (SOAP) technology because REST leverages less bandwidth, making it more suitable for internet usage. An API for a website is code that allows two software programs to communicate with each another . The API spells out the proper way for a developer to write a program requesting services from an operating system or other application.

The REST used by browsers can be thought of as the language of the internet. With cloud use on the rise, APIs are emerging to expose web services. REST is a logical choice for building APIs that allow users to connect and interact with cloud services. RESTful APIs are used by such sites as Amazon, Google, LinkedIn and Twitter.

How RESTful APIs work

A RESTful API breaks down a transaction to create a series of small modules. Each module addresses a particular underlying part of the transaction. This modularity provides developers with a lot of flexibility, but it can be challenging for developers to design from scratch. Currently, the models provided by Amazon Simple Storage Service, Cloud Data Management Interface and OpenStack Swift are the most popular.

A RESTful API explicitly takes advantage of HTTP methodologies defined by the RFC 2616 protocol. They use GET to retrieve a resource; PUT to change the state of or update a resource, which can be an object, file or block; POST to create that resource ; and DELETE to remove it.

With REST, networked components are a resource you request access to -- a black box whose implementation details are unclear. The presumption is that all calls are stateless; nothing can be retained by the RESTful service between executions.

Because the calls are stateless, REST is useful in cloud applications. Stateless components can be freely redeployed if something fails, and they can scale to accommodate load changes. This is because any request can be directed to any instance of a component; there can be nothing saved that has to be remembered by the next transaction. That makes REST preferred for web use, but the RESTful model is also helpful in cloud services because binding to a service through an API is a matter of controlling how the URL is decoded. Cloud computing and microservices are almost certain to make RESTful API design the rule in the future.

The model-view-controller (MVC) has been the traditional architectural pattern for developing applications having user interface, which later on evolved to MVP and MVVM architectures, as Martin Fowler explains.

Therefore, when listing the pros of MVC, I would basically compare it to the time before its existence, and for the cons I compare it to its successors, namely MVP and MVVP.

Pros:

MVC renders testability, maintainability and scalability. It also satisfies Single Responsibility Principle of SOLID. So it was a huge achievement at its time.

Cons:

1- View depends both on Controller and Model

This means there is not a single source of updating the View. In fact, if updating the UI requires data (e.g. from network or database), the View gets it from the Model. If not (e.g. hiding or showing the progress bar or going to another activity), the View gets the updates from the Controller.

Therefore, for unit testing the View, both Controller and Model must be mocked.

2- Model is doing too much work

It does too many things from getting the data from the network/database to informing the Controller about whether it could get the data or not, and even preparing the result to be displayed on the View.

3- Who controls the UI logic?

Should the View show the data it gets from the Model directly to the user?

if true, then the Model is handling the UI logic, which is intuitively not appropriate. Otherwise, View handling the UI logic is not good as well, since the View should only know how display the UI rather than judging on the content it displays.

JAX-RS: Java API for RESTful Web Services (JAX-RS) is a Java programming language API spec that provides support in creating web services according to the Representational State Transfer (REST) architectural pattern. JAX-RS uses annotations, introduced in Java SE 5, to simplify the development and deployment of web service clients and endpoints.

From version 1.1 on, JAX-RS is an official part of Java EE 6. A notable feature of being an official part of Java EE is that no configuration is necessary to start using JAX-RS. For non-Java EE 6 environments a small entry in the web.xml deployment descriptor is required.

Implementations of JAX-RS include:

Apache CXF, an open source Web service framework

Jersey, the reference implementation from Sun (now Oracle)

RESTeasy, JBoss's implementation

Restlet

WebSphere Application Server from IBM:

Version 7.0: via the "Feature Pack for Communications Enabled Applications"

Version 8.0 onwards: natively

WebLogic Application Server from Oracle, see notes

Apache Tuscany (http://tuscany.apache.org/documentation-2x/sca-java-bindingrest.html), discontinued

Cuubez framework (http://www.cuubez.com)

Everrest, Codenvy's Implementation

Jello-Framework, Java Application Framework optimized for Google App Engine, including a powerful RESTful engine and comprehensive Data Authorization model.