Understanding the Response

As the REST API's response is consumed by some application and not the browser, so we don't have to worry about styling it to make it look good.

In case of API response, it can be simple XML or JSON or any other media type. Also, at times, one REST API is being consumed by different applications. Out of which, one application might need the response in the form of XML and other might need the response in the form of JSON. We can develop such REST API, programming them to send the response according to the input header of the HTTP request.

There is a Media-Type attribute in the header which can be used in such cases and the response can be sent accordingly. We will learn how to do this in coming tutorials but for now lets concentrate on the design aspects of the REST API.

If we talk about the Student record, in our Student-Courses Application, the response will be something like this,

The Student class (Data Model/Object) will look something like this (using Java):

public class Student{
    private int rollno;
    private String firstName;
    private String LastName;
    private int age;
    private String contactNumber;
    ...
}

The XML response will be something like this:

<Student>
    <rollno>10</rollno>
    <firstName>Amit</firstName >
    <lastName>Agarwal</lastName>
    <age>25</age>
</Student>

The JSON response will be something like this:

{
    "rollno":"10",
    "firstName":"Amit",
    "lastName":"Agarwal",
    "age":"25"
    "contactNumber":"98877271127"
}

The above response is not the complete response its just the response body. An HTTP response contains the status line, headers and the message/response body.

As we have already discussed that same REST API can return both XML or JSON as response message, depending upon the Media-Type attribute in the HTTP request.

The question here is, how will the client know, what type of response to expect from the API. This is again managed by the response headers. There is a Content Type attribute in the headers which informs about the type of response body format.

Response(Status) Codes

Till now, we have discussed about the situations where everything is good but this doesn't happen in the real world scenario. You may have seen many times, that a particular website is down or not functioning properly. The same can also happen to the REST Api which you have developed and deployed on the server.

There can be many scenarios, like:

The server on which you have deployed the Rest API is down.
The client request is incorrect.
The resource which the client is requesting doesn't exist.
Some error occured on the server side while processing the request.

So the REST API must always return an appropriate status code to the client so that the client can know the actual issue and process accordingly.

Below mentioned are the standard status codes, used in HTTP responses.

1XX Codes: Informational Codes

These are the acknowledgement responses, used to pass on information. This status code is not used commonly.

2XX Codes: Success Codes

These are the success codes which means that the server has received the request from the client and processed it successfully.

For Example:

200 OK: This informs the client about the successful response.
201 Created: This should be returned for POST requests, stating that the resource is created successfully on the server. Like, when the client sends: POST /myApp/students/ request and the student recourse is created successfully then the server should return 201 Created as status code. The server can also return 200 OK, but it's always good to be more precise, and send 201 Created in case of a POST request.
202 Accepted: This informs the client that the request has been successfully received, but the processing is not yet finished.
204 No Content: This informs the client that the request has been successfully processed, but no content will be returned.
Check this for the complete list of 2XX status codes: 2XX Status Codes

3XX Codes:

These codes are generally used in case of URL Redirection.

4XX Codes:

This class of status codes are returned if the client's request has error. The request could be incorrect or the resource which the client is looking for doesn't exist.

400 Bad Request: There is something wrong in the request from the client, hence the server cannot or will not process it.
401 Unauthorized: The client needs to authorize themselves to make this request.
403 Forbidden: This status code is used when the client request is correct but the server refuses to process the request. The client might not have required permissions.
404 Not Found: The resource which the client is requesting for doesn't exist.

5XX Codes: Server error

The 5XX status codes are when server fails to process the request and cannot send the correct response. In this case the client doesn't have to change its request as the problem is with the server where the REST API is deployed.

500 Internal Server Error: This is a generic status code returned when an unexpected condition is encountered on the server, while processing the request.
503 Service Unavailable: When server is not available due to excessive load or may be down for maintainence, this status code is returned to the client.

Status Codes and our Registration API

In case of our Registration REST Api, we will have to send various Status Codes, whenever a request is received.

Lets summarize the test cases and their probable responses.

Operation	URI	Method	Success/Failure	Status Code
GET student record	`myApp/students/{rollNo}`	GET	Success	200
			Not Found	404
			Failure	500
DELETE student record	`myApp/students/{rollNo}`	DELETE	Success	200 or 204
			Not Found	404
			Failure	500
UPDATE student record	`myApp/students/{rollNo}`	PUT	Success	200
			Wrong Format/Data	400 or 415
			Not Found	404
			Failure	500
CREATE student record	`myApp/students/{rollNo}`	POST	Success	201
			Wrong Format/Data	400 or 415
			Failure	500