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.
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:
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.
These are the acknowledgement responses, used to pass on information. This status code is not used commonly.
These are the success codes which means that the server has received the request from the client and processed it successfully.
For Example:
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.These codes are generally used in case of URL Redirection.
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.
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.
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 |
/rest-web-service/understanding-the-response