Tuesday, June 25, 2013

REST - Resource Naming

REST can help a lot when we talk about integration, however not used correctly, it could bring future problems. This article will talk about some of the best practices for creating a REST API.

Use nouns instead of verbs

Keep the URI simple and intuitive. This will leave the API with a easier understanding and better to work with. A good way to test if the API was written correctly is making sure it has only 2 base URIs. For example:

This will return a collection of orders.
This can be used to GET (READ), POST (CREATE), PUT (UPDATE) or DELETE depending on the HTTP verb chosen.
This would return a collection of items from that particular order.
Using URIs with a non consistent pattern (using verbs) could end up causing a bigger effort for developers to understand and use the API.

Plural nouns

Being consistent, establishing patterns, when designing a API is very important. Another common guideline is using plural nouns. Observe that finding resources in REST can be compared to search for documents in a disk.
/documents       //(this would bring a list of documents)
/orders          //(this would bring a list of orders)
The difference between these two is that in REST, when getting a particular resource, id should be passed to use the resource, differently from the file system that file name would do it.

Concrete names rather than abstract

Sometimes developers look for a higher level of abstraction. Which sometimes bring less value for the API. Check out the next example:

Higher level of abstraction

Lower level of abstraction

Using a higher level of abstraction, in this case, will not bring as much value for developers dealing with the api, while the lower level should allow the user to have a better understanding of the resources. This level, of course, should be defined accordingly to each cenario.

Also expose a manageable number of resources. Aim for concrete naming and to keep the number of resources between 12 and 24.

This is it for today, we will continue to talk about REST best practices in the next articles. Remember intuitive API uses plural rather than singular nouns and concrete rather than abstract names.

Web API Design - Brian Mulloy

Monday, June 17, 2013

What is REST?

REST (Representational State Transfer) has become popular these days because of the high need for integration what consequently makes it very important for every developer to know and understand. This article aims to give you a guidance in what rest is and how can you use it to improve your applications.

REST describes an architectural style of networked systems such as web applications. It was first introduced in 2000 in a Ph.D dissertation by Roy Fielding, one of the principal authors of the HTTP specification. REST refers to a collection of architecture constraints and principles, which some will be shown next.

Uniform Interface

The central feature that distinguishes the REST architectural style from other network based styles is its emphasis on a uniform interface between components. Components can be origin servers, gateways, proxies or user agents (browsers).

The term uniform interface is used to describe how a (small) number of verbs with well-defined and widely accepted semantics are sufficient to meet the requirements of most distributed applications. A collection of verbs is used for communication between systems. You can check the example below which uses these verbs.

REST is defined by four interface constraints: identification of resources, manipulation of resources through representations, self-descriptive messages, and, hypermedia as the engine of application state.

Identification of resources

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a collection of other resources or even a person. REST uses a URI (unique resource identifier) to identify the particular resource involved in a interaction between components, as you saw on the previous example where a order is identified by /order/{orderId}. 


REST components perform actions on a resource by using a representation to capture the current or intended state of that resource. Representations consists of data or metadata describing the data. The response should include both, representation metadata and resource metadata. This data format of a representation is known as media type. A resource can be provided in multiple media types and you can choose the one that best fits the application.

You could ask the server to give you a "order" with the media type application/json, for example, because your client is mobile so you need less data. Or maybe you have an external client that needs to read another format like XML, then he just have to ask the server for an application/xml and it will give you the data you want.


This is an important principle of REST which requires that every interaction between components must be stateless. It means that every response must have all the information for that request to be fully understood. The right way of controlling state in REST is using HATEOAS. 

Hypermedia as the engine of application state (HATEOAS)

REST concentrates all the control state into the representations received in response to interactions. The goal is to improve server scalability by eliminating any need for the server to maintain an awareness of the client state beyond the current request. On the example below you can see that the order already gives you the link within payment for the next transaction step maintaining the transaction control on the client-side.

Self-descriptive messages

Another constraint of REST is that messages should be self-descriptive and with all information needed for the task to be completed.

Well, that’s it. Now you have a guidance in how REST works. We’ll continue to talk about it in further articles.

See you later!


Roy Thomas Fielding dissertation, 2000.
REST in Practice book, 2010.

Wednesday, June 5, 2013

Restful project with Maven Archetype and Jersey

Hi everyone, this is my first post and hope you like it.

Today we will talk about building a Restful project using maven and jersey libraries. For this to be possible maven archetype, a tool to build projects out of templates, will be used.

In this tutorial we will be using command line maven, you can download and follow the installation intructions on http://maven.apache.org/download.cgi.

After installation follow the steps below:

1 - Go to your workspace and type:

mvn archetype:generate -DarchetypeCatalog=http://download.java.net/maven/2

2 - Archetypes will be downloaded from the catalog. After downloading you'll see this message "Choose a number or apply a filter", type 3.

3 - After selecting rest archetype, you will fill the project configuration information according to the example below:
groupId - br.com.restful (Identifies your project uniquely between all your projects)
artifactId - blog-restful-webapp (Represents the war name without version)
version - 1.0 (Identifies the project version)
package - br.com.restful (Represent the package structure)

4 - Next, a confirmation message will show up, just type Y and your project will be created.

5 - After the project have been created, type: 

mvn clean install (Clean and build)

6 - The result of previous step should be BUILD SUCCESS, which means that now you already have your rest project fully configured, compiling and ready to be executed.

After doing all these steps you will have import the project into your IDE. In this example eclipse will take place, but be free to use your prefered IDE since maven is IDE agnostic.
Open eclipse and click with the mouse right button on Project Explorer -> Import -> Existing Maven Projects, select your project and click Finish.


Now you can take a look on the class created by the template in br.com.restful.MyResource.

Next, click on the mouse right button over the project and run on your server. In this example we used Tomcat 6.

A page like this should appear.

To access the GET method you just have to access the link:
http://localhost:8080/blog-restful-webapp/webresources/myresource, remember that port should be set accordingly to the server configuration. On this case we used tomcat default port which is 8080.

The template initial configuration establishes that all rest services stays below webresources. This could be easily changed but this is a subject for other post.

Hope you enjoyed it and see you later.