5 Common API Mistakes to Avoid
Contents
Whether you are consuming or developing an API, it is very frustrating to see an error. What’s even more annoying is that you can’t find out what’s wrong. It is very common for a developer to do silly mistakes like making a typo in the code or missing out a parenthesis.
Sometimes, we fail to identify the cause of an error because the mistake is tiny and it is easy to be overlooked. To reduce frustration in your development (and make your life easier 🙂), here are 5 common API mistakes that you could avoid:
1. Using “http://” Instead of “https:// “
Using “ http://” instead of “ https://” when making an API call is quite common when a developer accidentally misses out on an ‘s’ or is confused with both. The only difference between the two protocols is that HTTPS is HTTP with encryption. HTTPS uses an encryption protocol called Transport Layer Security (TLS) or formerly known as Secure Sockets Layer(SSL) which secures communication.
If a website uses HTTP instead of HTTPS, all requests and responses can be read by anyone who is monitoring the session. If you are using HTTPS, the attacker would only see a bunch of random characters.
Most API endpoints use HTTPS nowadays as it helps to guarantee confidentiality, authenticity, and integrity. If you are trying to access an HTTPS endpoint using HTTP, here are two possible outcomes:
Get Redirected to HTTPS
A request to a “http://” link can be configured to be redirected to the secure “https://” version. The redirection rule is often written in the web.config file located in the root directory of the application. If it is configured to be redirected, it can be redirected using one of these redirect types:
- Permanent (301)
- Found (302)
- See Other (303)
- Temporary (307)
Get an Error Message
Not all frameworks will be configured for HTTPS connections or successfully follow redirects. In this case, you might get an error like these:
- 400 Bad Request
- 500 Internal Server Error
- 403 Forbidden
- 404 Not Found
As suggested by CIO.gov, all APIs should use and require HTTPS to help guarantee confidentiality, authenticity, and integrity. Therefore, it is sensible that you should always call the HTTPS endpoint to avoid this error.
2. Omitting Content-Type Header
In requests such as POST and PUT, the client tells the server what type of data is sent in the request body via the Content-Type header.
Some APIs will accept the request even if the Content-Type is not specified. If the Content-Type is not set, the server may try to guess the media type via inspection of the request’s content or the name extension of the URI used. If the media type is unknown, it will assume the data is application/octet-stream.
There are also some APIs that need the Content-Type to be set explicitly in the header. If a server allows and accepts multiple types of content, it can use this field to know how to interpret the body of the request.
You might not need to specify the Content-Type for a GET request as it doesn’t contain an entity-body normally. On the other hand, a POST or a PUT request often contains an entity-body. Although it is not mandatory to specify the Content-Type for these requests, it is advisable to do so so that the server can accurately interpret the data received.
Some common values that can be used are:
application/x-www-form-urlencodedmultipart/form-dataapplication/jsontext/plain
However, you need to make sure that the Content-Type specified is correct. The request will fail if it is wrong. For example, if the server only accepts application/json requests and your Content-Type is set to text/plain, you might get a 415 Unsupported Media Type error. The server refuses to accept the request because the payload format is unsupported.
3. Sending Invalid Authorization Header
The Authorization Request Header, Authorization is sent to the server to authenticate the identity of a user. Some common types of Authorization Request Headers are Basic Authentication, Bearer Token, OAuth 2.0, etc.
A mistake that could happen when adding the Authorization Request Header is accidentally writing “Authorization” as “_ Authentication ”._ Authentication and authorization can be easily confused as they share the same “auth” abbreviation. While they might sound similar, they are two different security processes that are essential to protect systems and information.
Authentication verifies the identity of a user while authorization determines a user’s access right and gives the user permission. After the user is authenticated, it does not mean that the user will be able to access all API endpoints or resources. The user will only be able to access those which the user has permission.
This mistake could cause the server to receive a request without valid credentials and return a 401 Unauthorized or 403 Forbidden response. It could also return a 404 Not Found response as as security measure to avoid unauthorized user from knowing that the endpoint really works.
Depending on the type of authentication used, the Authorization header could be different. The syntax of the Authorization header is:
Authorization: <auth-scheme> <authorization-parameters>
For example, if the type of authentication is Basic Authentication , the header would be Authorization: Basic <credentials>. If the type is Bearer Token, the header would be Authorization: Bearer <credentials>. It is important that the prefix ‘Basic’ or ‘Bearer’ is included in the header and the correct prefix is used to make sure that the Authorization header is valid.
4. Assuming Browser Must Receive the Same Response as API Client
Have you ever faced a situation where your request is successful when using an API client like Postman or Insomnia but it fails when sending the request from a browser? It could be frustrating when you see an error like this:
The error above states that the request has been blocked by CORS policy: Response to preflight request doesn’t pass access control check: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.
This error occurs because browser like Chrome will send a preflight Options request in order to ascertain what cross-domain parameter it is allowed to send to the server. It also checks whether the response returned has Access-Control-Allow-Origin to authorize its origin.
When you make a cross-origin request from a browser, the browser adds an Origin header to the request. If the server does not set the Access-Control-Allow-Origin to allow your domain, you will get a Cross-Origin Resource Sharing (CORS) error.
This does not happen when you are making a request from an API client like Postman because it does not perform CORS check. It does not send a preflight Options request before the actual request like how a browser does.
If you are developing an API, do not assume that a browser must be able to make an API request successfully because you have tested it using an API client. Make sure that it is configured properly to avoid this problem.
In the response header, you can add Access-Control-Allow-Origin: * to allow any origin. Be cautious when you are using this as it can make your API vulnerable to cross-site request forgery (CSRF) attacks. If you are only allowing requests from certain origins, specify the origin instead: Access-Control-Allow-Origin: https:www.yourwebsite.com.
5. Sending Invalid Fields
If you are sending a request with a body, it is important to provide all the data that is needed. For cases where the server checks the mandatory fields when the request is received, the server would return a response specifying which field is missing.
Sending invalid fields doesn’t only refer to missing out fields when sending a request. Sometimes you could send a request with additional fields which are not needed. Depending on how it is handled, the request could be rejected or accepted with the redundant field ignored.
It is also possible that an API could return a 500 Internal Server Error without any other information. In this case, it could be quite a headache to find out what is wrong. Make sure to check the API documentation to make sure that you are sending correct data in you request. If you get an error, double-check the documentation to troubleshoot your error.
These are 5 common API mistakes that you could avoid to save yourself from frustration. What are other common mistakes that are easily overlooked? Write them down in a list so that you can identify the cause of error easily when you accidentally make them next time.
