rest overview.html - swisscom-api/doc GitHub Wiki

title: REST Overview owner: API

<%= modified_date %>

What is REST?

REST stands for REpresentational State Transfer, which describes the architectural style of using HTTP to make remote procedure calls. Instead of using a heavy RPC mechanisms such as XML-RPC or SOAP, a REST web API uses the design of the HTTP protocol to define the remote methods.

Almost everyone with a technical background understands what an HTTP GET call is, but it is less understood that HTTP has a vocabulary of operations that is very similar to the CRUD calls needed to maintain the state of entities. What most people call an URL is often called a resource in REST. Each resource can be called with a given operation which is called a HTTP method. Here is a list of the most common HTTP methods called in REST and the CRUD equivalent:

REST CRUD
POST Create
GET Read
PUT Update
DELETE Delete

REST Example: User API

Let's go through an example of a fictional REST API for managing users. The following table shows the different resources and methods to manipulate user entities:

REST Call HTTP Method Resource (URL) Notes
List users GET http://swisscom.ch/api/user Get a list of the users in the system, which in most cases will be a summary view. It is also common to allow the use of keywords via attributes such as http://swisscom.ch/api/user?firstName=Humpty to limit the list to users have the first name of "Humpty".
Create user POST http://swisscom.ch/api/user This call makes a POST call to the same URL resource as the list users. You will need to send the create attributes in the post request. This is commonly done by sending a payload of attributes in JSON format. For example, to create a user in our system named Humpty Dumpty, we would send a payload like this: 
{
  "firstName" : "Humpty",
  "lastName" : "Dumpty",
  "userName" : "hdumpty",
  "email" : "[email protected]",
  "status" : "active",
}
Get user GET http://swisscom.ch/api/user/hdumpty Get a user and all details. Note the URL has the unique ID representing the user.
Update  user PUT http://swisscom.ch/api/user/hdumpty Update the user w/attributes sent in the payload, just like the create user request. For example, to change the status of Humpty Dumpty to "broken": 
{
  "firstName" : "Humpty",
  "lastName" : "Dumpty",
  "userName" : "hdumpty",
  "email" : "[email protected]",
  "status" : "broken",
}
Delete user DELETE http://swisscom.ch/api/user/hdumpty Since no one could put Humpty back together again, the DELETE call to the hdumpty resource URL will remove him.

Why REST?

Swisscom has decided to expose services via REST due to the simple nature of REST APIs for the following reasons:

  • Easy to understand: Instead of using a more complex RPC mechanism such as SOAP, a REST API helps developers get up and running quickly. REST is easy to read and understand, and can be tested by using a standard browser.
  • Language neutral: REST is easy to implement in any language - every modern programming language will have HTTP and JSON encoding methods built into the language. Most languages also have multiple open source libraries that make REST calls even easier.
⚠️ **GitHub.com Fallback** ⚠️