RESTful Web Services – Messages

RESTful web services provide a standard way for applications to communicate with each other over the internet. They use HTTP protocol to exchange messages in various formats such as XML, JSON, and plain text. In this article, we’ll discuss the different types of messages that RESTful web services use and how they work.

HTTP Requests

HTTP requests are the messages sent by a client to a server to request a resource. RESTful web services use the following HTTP methods to indicate the type of operation that needs to be performed on a resource.

HTTP Method	Operation	Idempotent
GET	Retrieve a resource	Yes
POST	Create a new resource	No
PUT	Update an existing resource	Yes
DELETE	Delete a resource	Yes

The HTTP method is sent as part of the request line and the URL of the resource is sent as the first line in the request message header. Along with the URL, the header can also include additional information such as authentication tokens, content type, and language.

Here is an example of an HTTP request to retrieve a list of customers in JSON format.

GET /api/customers HTTP/1.1
Host: example.com
Accept: application/json

HTTP Responses

HTTP responses are the messages sent by a server to a client in response to a request. RESTful web services use the following HTTP status codes to indicate the outcome of the request.

HTTP Status Code	Description
200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

The HTTP status code is sent as part of the response line and the message body can contain the requested data or an error message if the request was unsuccessful. Along with the message body, the header of the response message can also contain information such as content type, language, and caching policies.

Here is an example of an HTTP response to retrieve a list of customers in JSON format.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
{
  "customers": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    {
      "id": 2,
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}

HTTP Headers

HTTP headers are part of both request and response messages and contain metadata that provide additional information about the message. Some commonly used headers in RESTful web services include:

• Content-Type: Indicates the format of the message body.
• Accept: Indicates the format(s) of the response message that the client is willing to accept.
• Authorization: Provides authentication information for the request.
• Cache-Control: Specifies caching policies for the response message.

Here is an example of a request header that includes authentication information.

POST /api/customers HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

{
  "name": "John Doe",
  "email": "john.doe@example.com"
}

Content Negotiation

Content negotiation is a mechanism used by RESTful web services to select the best format for data exchange based on the client capabilities and server preferences. The Accept header in the request message indicates the formats that the client can understand, while the Content-Type header in the response message indicates the format of the data being returned.

Here is an example of a request header that indicates the client can accept either XML or JSON formats.

GET /api/customers HTTP/1.1
Host: example.com
Accept: application/xml, application/json

The server can then use this information to choose the appropriate format for the response. If both XML and JSON formats are supported, the server might choose JSON because it is a more efficient format for data transmission.

Conclusion

RESTful web services use messages to communicate between clients and servers. HTTP requests are used to request resources, which are then returned in HTTP responses. HTTP headers contain metadata that provide additional information about the messages, such as content type and caching policies. Finally, content negotiation is used to select the best format for data exchange based on client capabilities and server preferences.