New tools have made developing REST/API very easy for any aspiring Java Developer. But there is still a big difference between ‘developing’ an API and making one that:
- Performs the required task and is
- Reliable and
Most Java coders tend to make similar mistakes when developing a REST/API.
Using Body in GET Requests
In a GET request, developers need to add parameters inside the body, not in a URL. Doing so can cause problems. Because a payload within a GET request message does not have proper semantics. So if a payload body is sent on a GET request, there is the possibility that it will get rejected.
Any HTTP request message is allowed to contain a message-body, so it must parse messages accordingly. But the server semantics for GET are restricted such that a body has no semantic meaning to the request. The requirements on parsing are different from the requirements on the method semantics.
In other words: Yes you can send a body with GET. (As many developers do). But it is never fruitful to do so.
Using The Wrong Method
The use of the wrong method, be it GET, PUT, or POST is another area where developers go wrong. This usually happens when the API developer relies on past assumptions. As a developer, you risk using the wrong method. i.e. It might do the job. But it is not the best one to use.
Top talent distinguishes itself by:
- First gaining a strong understanding of each function and its uses and
- Then developing an API to avoid mistakes.
Defining Their Own Error Code And Error Message
Error handling in many APIs is implemented in a way such that all requests return a response code of 200. Even if there is an error. That leaves no other means than to parse the body and check for errors. Is that the best way to distinguish successful and unsuccessful responses?
Not according to top software engineers. They have proposed an alternative. A “problem details response,” properly defines the interface of a correct and well-known error response. Most Java coders overlook its use because they are unfamiliar with it.
Another good practice is using standard HTTP error codes. Most clients and developers recognize them. Also, it makes things easier if the API client knows upfront whether to parse the body or not.
Consider cases where errors are application-specific: Returning a code with an appropriate error message in the response body will be easier to understand.
Developers need to be:
- In compliance with widely-adopted HTTP standards
In whichever error handling tactic they choose for a given API.
It is a common habit of Java Developers to ignore caching. They do this by including a header, “Cache-control: no-cache” in responses of the API calls. HTTP defines a powerful caching mechanism that includes ETag header. The ETag (entity tag) response header provides a mechanism to cache unchanged resources. Its value is an identifier that represents a specific version of the resource.
This allows your clients and servers to negotiate a new copy of the resource every time. And through caching or proxy servers, this increases your application’s scalability and performance.
Returning Too Much Data And Poor Response Times
Developers often forget that the resources they are returning can increase both ways. In count and in size.
This can cause unnecessary increase in the load on microservices. And it will also increase the response time of the REST API. Pagination, sorting, and filtering can address all these issues.
URL parameters are a basic approach towards adding basic filtering to REST APIs. E.g. If you have a “/courses endpoint” that lists courses you are enrolled in, you can: filter via the property name such as GET /courses?state=active or GET /courses?state=active&student=111. But this only works for exact matches and not for a range of data.
Pagination is essential. Without pagination, a simple search would return lots of hits and create irrelevant traffic.
For example, Limit/Page Paging would look like GET /courses?limit=10&page=5. This query would return the 10 rows starting with the 100th row (5 pages of 10 items). Not sending the page, would default it to 0.
Like filtering, sorting is an important feature as well. Especially for any API endpoint that returns a large amount of data. To enable sorting, many APIs add a sort or sort by URL parameter that can take a field name as the value.
Good API designs give users the flexibility to specify ascending or descending order. Specifying the order requires encoding 3 components into a key/value pair. (Like filters).
One of most common mistakes developers make is that they do not specify either the:
- ‘accept’ header or the
- ‘content-type’ header.
Some APIs do not need these headers in their requests but other APIs are quite rigid about it. If the header is missing, the requests will fail. That is why it’s important that developers always include them. These headers specify the format of the information that will be sent or received between the client and the server.
These mistakes are very common. But as we see, they come with their own remedial techniques. Top talent also proactively seeks out:
- Workshops and trainings and
- Proper testing for APIs for a certain period to fix such problems.
What remains necessary is for every Java Developer to focus on the concepts behind the tools.