Web Services
Web services technology is a fast mode of distributing information between customers, suppliers, business partners and their various platforms. Web services are based on the "Service-Oriented Architecture" (SOA) model.What is an API?
The term API stands for Application Programming Interface. The term can be used to describe the features of a library, or how to interact with it. Your favorite library may have "API Documentation" which documents which functions are available, how you call them, which arguments are required, etc.However, these days, when people refer to an API they are most likely referring to an HTTP API, which can be a way of sharing application data over the internet. For example, Twitter has an API that allows you to request tweets in a format that makes it easy to import into your own application. This is the true power of HTTP APIs, being able to "mashup" data from multiple applications into your own hybrid application, or create an application which enhances the experience of using someone else's application.
A problem has started to arise when everyone starts implementing their own APIs. Without a standard way of naming URLs, you always have to refer to the documentation to understand how the API works. One API might have a URL like "/view_items" whereas another API might use "/items/all".
This is one of the reasons to develop Rest (or RESTful) Web services.
What is REST?
REST stands for Representational State Transfer. This is a term invented by Roy Fielding to describe a standard way of creating HTTP APIs. He noticed that the four common actions (view, create, edit, and delete) map directly to HTTP verbs that are already implemented: GET, POST, PUT et DELETE. (RFC2616 - Hypertext Transfer Protocol -- HTTP/1.1)HTTP methods
There are technically 8 different HTTP methods. For DairyTrace, the following methods are implemented:Method | Description |
---|---|
GET |
Request for the resource located at the specified URL |
POST |
Sends data (add) to the program located at the specified URL |
PUT |
Sends data (update) to the specified URL |
DELETE |
Deletes the resource located at the specified URL |
HEAD |
Request for the header of the resource located at the specified URL |
Examples of REST
Let's look at a few examples of what makes an API "RESTful". Using our items example again...- If we wanted to view all items, the URL would look like this:
GET http://example.com/items
- Create a new item by posting the data:
POST http://example.com/items
Data:
name = Name - To view a single item we "get" it by specifying that item's id:
GET http://example.com/items/123
- To validate the existence of a single item we send a HEAD command by specifying that item's id:
HEAD http://example.com/items/123
- Update that item by "putting" the new data:
PUT http://example.com/items/123
Data:
name = New name
color = black - Delete that item:
DELETE http://example.com/items/123
Anatomy of a REST URL
You might have noticed from the previous examples that REST URLs use a consistent naming scheme. When you are interacting with an API, you are almost always manipulating some sort of object. In our examples, this is an Item. In REST terminology, this is called a Resource. The first part of the URL is always the plural form of the resource: /itemsThis is always used when referring to this collection of resources ("list all" and "add one" actions). When you are working with a specific resource, you add the ID to the URL: /items/123
This URL is used when you want to "view", "edit", or "delete" the particular resource.
HTTP Status Codes
Another important part of REST is responding with the correct status code for the type of request that was made. If you're new to HTTP status codes, here’s a quick summary. When you make an HTTP request, the server will respond with a code which corresponds to whether or not the request was successful and how the client should proceed.There are five different levels of codes:
Code | Description |
---|---|
1xx |
Information |
2xx |
Success |
3xx |
Redirect |
4xx |
User Error |
5xx |
Server Error |
Here is a list of the status codes used by REST APIs:
2xx – Success Codes | Description |
---|---|
200 |
OK. Successful response. The actual response will depend on the request method used. |
201 |
Created. The request has been fulfilled, resulting in the creation of a new resource. |
204 |
No Content. The server successfully processed the request and is not returning any content.. |
4xx – User Error Codes | Description |
---|---|
400 |
Bad Request. The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). |
401 |
Unauthorized. The user does not have the necessary credentials. |
404 |
Not Found. The requested resource could not be found but may be available in the future. |
405 |
Method Not Allowed. A request method is not supported for the requested resource. |
406 |
Not Acceptable. There is a validation error. Consult the response body to analyse the errors. |
415 |
Unsupported Media Type. The request entity has a media type which the server or resource does not support. |
HTTP message request field
Request Headers
The request header fields allow the REST service client to give additional information about the request. Here are the most commonly used request header by a client to a web service REST:Request Header Fields | Description |
---|---|
Acccept |
Content-Types that are acceptable for the response. |
Accept-Charset |
Character sets that are acceptable |
Accept-Language |
List of acceptable human languages for response. |
Authorization |
Authentication credentials for HTTP authentication. |
Content-Type |
The MIME type of the body of the request (used with POST and PUT requests). |
User-Agent |
For reasons of safety, each custom application that will access the
REST protocol must have an HTTP header type "User-Agent".
This header will help us identify which applications are accessing our
servers and it will be easier to offer support. We suggest including the
name of your company, an application ID and version. Example: User-Agent: Company-Apps-Version1 |
Connection with the Authorization header:
Example:- Connection information (before base64 encoding): Basic myUsername:myPassword
- Connection information (after base64 encoding): Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk
- Final Authorization Header: Authorization: Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk
Response Header
The response header fields allow the service to give additional information about the response. Here are the most commonly used response header used by a REST web service:Response Headers | Description |
---|---|
Allow |
Fields to inform the client of the methods, character and / or languages valid associated with the requested resource. |
Content-Length |
Body length of the response. |
Content-Type |
Content type (format) of the body of the response. |
Vary |
Informs the customer on the criteria that were used to choose the representation of the requested resource. |
Location |
For 201 (Created) responses. The location is that of the new resource which was created by the application. |
Warning |
Carries additional information about the status or transformation of a message which might not be reflected in the message. |
Status |
This is the HTTP return code of the response (Status: HTTP/1.1 405 Method Not Allowed). |
X-Service-Ati-Id |
When a record is made. The unique identifier of the new record will be in this header (X-Service-Ati-Id: 12345). |
API response formats
When you make an HTTP request, you can select the format that you want to receive. For example, making a request for a webpage, you want the format to be in HTML, or if you are downloading an image, the format returned should be an image. However, it's the server's responsibility to respond in the format that was requested. JSON has quickly become the format of choice for REST APIs. It has a lightweight, readable syntax that can be easily manipulated. So when a user of our API makes a request and specifies JSON as the format they would prefer:GET /items Accept: application/json
Will return a JSON format :
[
{
id:123,
name:'Simple Item'
},
{
id:456,
name:'My other item'
}
]
Note that our API uses only JSON.