API Security Best Practices

SB Karunarathne

With the evolution in computing over time, we are living in a world where the control of most of the things are at our fingertips. We have the capability to get most of our day to day needs using a computing device such as a mobile phone or any other smart device using very little effort. With the growth of computing, today scientists and engineers have built AI models with greater IQ rates.

Behind all these, it is a result of a communication of multiple systems to achieve the common goal. This is where the APIs come into picture. APIs help systems to communicate with external systems making available other systems to access its functionality. Nowadays APIs are heavily used almost everywhere enabling the whole world to be connected and everything held tight.

With the heavy usage of APIs on the other side we have a big threat of the improper or unintended usage of the APIs specially by hackers. Also if the APIs are not properly implemented, configured or used there is a potential to have the data lost or stolen by others. This is where the API security best practices we need to make them stable and save from vulnerable usages.

When we talk about securing the APIs we can do it from different levels. We need to plan the security of the APIs from the API design stage. Without a proper design of the APIs, there is a tendency to forget some of the facts that we have to take care of at the stage we do the real implementation of the APIs.

In this article we will look into a few of the security best practices under the following categories that we can take care of when we are going to build APIs.

• Development Practices
• Deployment and Access
• API Testing
• API Contracts and Documentation

Now let's have a closer look at each of the things we mentioned above to get a better understanding and why we need to take care about these.

Development Practices

APIs are the interfaces to access a built-in functionality of a system by outside consumers. So, if we have not properly designed and implemented the APIs, there is always a chance to gain access by unauthorized personnel and manipulate our business functionalities available in our system. So, the failure to protect from such incidents will directly impact on us with one or more of the following impacts.

• Interruption of service availability
• Loss of business information
• Disclosure of our business strategies
• Loss of reputation
• Loss of credibility
• Loss of consumer base
• Loss of Business

Other than the above mentioned impacts there are a lot of adverse effects that could be potentially affected on us for our business and social relationships. That’s why we need to have a proper design and implementation of APIs.

API developers should always follow the general API standards and also the best practices as much as they can. Following the standards, best practices and frameworks will help us to streamline our API implementation while reducing the number of possibilities to have such security loopholes in our APIs. So, our intention here is to give some of the developmental best practices to reduce such incidents. There are a lot of standards, best practices and frameworks available for these and we will be discussing some of the key concerns or practices here.

1. Selecting the Proper HTTP Method
   When we are dealing with APIs we need to identify the scope of the APIs and what kind of data we have to manipulate. Basically when we need to send some sensitive data, it is always better to use a POST API call rather than using a GET API call. The reason is when we use a GET API call, the data sent along with the GET API call are easily readable. But when we use a POST API call, the data is sent in the request body and relatively secure. With REST API standards, there are a set of HTTP methods defined based on the nature of the requirements. Some of such HTTP Methods are GET, POST, PUT, PATCH and DELETE.


2. Input Validation
   Validating the input is crucial as we can’t always expect we only get the data as expected. There is always a chance to receive unexpected data inputs for the APIs from both legal and illegal users. So, it is the responsibility of the API developers to filter out these improper data and react only for the valid data. Under the Input Validation we will be discussing a few things and the things we can do to improve them.


• Content Type Validation
  As the name depicts the content type refers to the content type of the incoming request. We can control the incoming requests based on the content type of the request. Usually this is configurable in the request to which type of contents are accepted by the API.


• Data Validation
  Validation of the data should be a general practice of good API developers. This is very important because there could be situations like the attackers may try to execute SQL injections or some other malicious contents to gain the control of the system or spoil our data. Also, invalid data could cause issues for the data integrity. So, it is always better to do a proper data validation before executing the other business functionalities to make sure we are processing valid data.
  
  
• Secure File Uploads
  Uploading files is one of the ways that a user can interact with a system. While allowing users to upload files, the API developers should try to make the capability limited to the desired functionality. Because if the user’s intention was to harm the system, then from the API side, there should be mechanisms to reduce the impact on the system. The following contains some of the ways that we can mitigate impact on the APIs in such incidents
• File type validation
  
• File size limitations
  
• Scan for malware
  
• Rate limiting
  
• Use of HTTPS
  
• Authentication and Authorization
  
Other than above-mentioned practices, generally we can have other validations like length validation, content validation, data type validation, encode and escape user inputs and also, we can implement specific customized validations. With all these input validation methodologies, it helps to leverage the security and the consistency of the data of the users.


3. Output Validation
   The term ‘Output Validation’ refers to the process of controlling and processing the data sent as the response for the API invocations. Usually the database may have stored some sensitive information along with other information. For example, we are saving authentication related information, transaction related information which are potentially risky if we expose to the outside. So, we need to take appropriate actions to prevent sending these data to the consumers or at least altering the content to avoid potential risks. Here we will be discussing a few of them to give a general understanding about the requirement.


• Skip Sending Confidential Information
  
In general practice, most of the time we will save all related information as a single entity. This may contain the general information and also other specific sensitive information. So, it is the developers responsibility to minimize information disclosure by not including highly secure information and send only the specific information without sending the secure information. For example, users’ data may have been saved in the database in a way like his general information along with his password and other tokens. So, when an API call is executed to retrieve user information, we should take appropriate actions not to send the sensitive information as the API response. This way, the external parties won’t be able to extract these information and misuse them.


• Altering the content and integrity validation
  Sometimes there could be some scenarios where still we need to send some sensitive data in the response as it is required by the consumer. But as we know we have a potential risk of accessing data by unauthorized personnel, we need to do some kind of alteration to data rather than sending them as plain data. The popular ways to do so are data encoding, data encryption for protecting the content and hashing for integrity validation.


• Data Cropping and Masking
  There are scenarios where we need to send some sensitive data to the consumers and still these data should be readable. So, we cannot have both of the above approaches. In this case what we can do is, we will be making a fraction of the data making it readable. We can achieve this by either cropping or masking a fraction of the data. A simple use case is showing the credit card numbers, bank account numbers, emails and phone numbers in a web page.
Other than the above mentioned we still can have other approaches like API access restrictions, defining additional security measures can be used. Some of them will be discussed in the rest of the article.


• Proper usage in HTTP Status Codes
  In REST APIs, we have standard HTTP status codes defined for different HTTP methods and different statuses. So, it is always better to return the standard response codes with other information. Then the API consumers can adapt the behavior according to the response they received. Improper response handling could cause information disclosure, security misconfiguration, cache poisoning, XSS attacks, CSRF exploitations and many more.


4. Authentication and Authorization
   If you are building APIs, one of our main considerations is controlling the access to APIs. One way of controlling the access to the APIs is through authentication and authorization. This process basically controls unauthorized access to the APIs and improves the assurance of the protected information.


• Authentication
  
Authentication helps to verify the identities of the users or clients against the provided security implementation. The clients have to prove the identity first before accessing the protected resources and information. There are different types of authentications based on the requirements of the system and the targeted audiences of the system. API Key authentication, Basic Authentication, Token Authentication, OIDC authentication are some of them. Even within these authentication types there are variations available that allow the developers to select most suitable authentication types for their systems. The authentication process basically denies the access to the system for any entity who cannot prove their identity.


• Authorization
  Sometimes the authentication is not just enough to access certain resources. We have to control access to certain resources based on the privileges assigned to a user or a role. For example, we cannot allow access to the manager level features for a general user. Validating the capability to access these kinds of features and check whether they have the permissions is called the authorization. Authorization process blocks unauthorized access by only allowing access to the entities or means who have proper permissions and privileges to the target resource or information.
  As the expectation of this article is to give the security best practices for APIs, we will not go into the details of each authentication and authorization process. If you are interested to study further on this, you can find more information about them from here.


• Handling passwords
  Passwords are the utmost important information that we have to protect as if someone manages to steal a password, he can do almost all the things the specific user can do. So, it is very much important to handle the passwords with extreme care. When we are saving the passwords, it is always better to hash the password with salt. Then it is almost impossible to guess the password by others just in case they were able to access the saved password. Also, we should not include the password in the API responses. Another common mistake we are doing in code, is we are treating a password as a string. In Java, the strings are handled in the string pool and if someone took a memory dump, it is possible to gain the password by them. So, it is better to treat a password as a char array instead of manipulating it as a string.


• Error Handling
  Error handling is a most important step in software development. If we do not handle the errors properly, there is a potential risk of creating data integrity issues. Also, there is a possibility of information disclosure and giving invalid status codes to the consumers which will create more issues like we discussed above. Also, while handling the errors, we also need to take care of logging the errors and do the needful to keep the system functioning without any issues while making room for the engineers to debug and troubleshoot the issues when required.


• Audit Logs
  When we are managing APIs, sometimes we will have to measure and audit the usage of the APIs. For example, we may need to get the matrices like what kind of users have used the APIs, how many users have used the APIs and the general usage patterns of the APIs.etc. In these kinds of scenarios, the system should be able to cater the needs. Audit logs are one way of providing the usage insights in such business requirements. Also, if we want to trace an issue or a misuse of an API, it will help us to track down easily if we have the audit logs.


• API Versioning
  API versioning is a strategy of allowing users to access different versions of APIs based on the requirements or the consumers. We may have different requirements and use cases of API versioning with regards to the API security best practices. backward compatibility, security patching, risk mitigation, authentication and authorization updates are some of the requirements we need for API versioning. Also, the API versioning provides smooth transitions and new features and also provides graceful deprecation for older API versions without breaking functionality with consumers for current API versions.


• Dependency Management
  Dependency management is a key concern and a best practice with regards to APIs. Because when we are dealing especially with third party libraries, there is always a chance for security breaches because of an issue with a code or misconfiguration in the third-party libraries. So, it is always better to keep an eye on these and identify the earliest before we are too late. If this is caught by an intruder, we won’t be able to imagine the damage he could do. It is the API providers’ responsibility to identify and define the proper dependencies and manage them properly. Also, it has the same importance to be on alert for new releases of the dependencies which may contain some fixes for security issues as well. Nowadays we can see new tools developed to identify and notify the updates of dependencies which makes the developers life much easier. Dependabot is an example for this.
Under the Development and Practices, we have discussed some of the most important facts that the developers have to take care of. Of course there are a lot more to consider which we have to pay attention to and ultimately help us to build great enterprise level APIs. Now let's focus on what kind of deployment level practices we have to take care of.

Deployment Practices

After the development of the APIs are completed, focus on the deployment related security best practices also have the same importance. In here we will be discussing a few actions or methodologies that we can carry out to reduce the potential security issues that the APIs will have to face.

1. Use of HTTPS/TLS
   In general, the usage of APIs over an HTTP protocol is not secure. But if we use HTTPS, we have end-to-end encryption for the communication. So, we are more confident about our data and resources as they are transferred over the network safely in the encrypted manner. Also, with the use of HTTPS, it prevents the man in the middle attacks. Other main advantages are data integrity, user trust/confidence, Protection against session hijacking and code injection attacks and many more.


2. CI/CD Pipelining
   The CI/CD automation helps to improve the security of the APIs indirectly. When we set up the CI/CD processes, we can also set up other jobs to be run along with the automated build and deploy process. For example, static code analysis, dependency scanning, unit testing, automated security testing, secure code reviews, security liners can be executed in the CI pipeline.


3. Use of Firewalls
   Firewalls play a crucial role in API security by providing a protective barrier between the API infrastructure and the potential threats. We can define different types of firewalls to provide different levels of protection for the APIs. Web Application Firewalls (WAF) can be used to protect against the common web attacks such as SQL Injection, Cross-site scripting (XSS) and cross-site request forgery (CSRF). WAFs allow you to define security policies to control and monitor HTTP traffic, ensuring adherence to security best practices. The API gateway firewalls can be used to control and filter the incoming API requests. This helps enforce access control policies based on IP addresses, authentication tokens, or other criteria.


4. Rate Limiting
   Another great advantage of the Application Gateway Firewalls is rate limiting. API rate limiting is a mechanism used to control the number of requests a client or user can make to an API within a specified timeframe. The primary goal of rate limiting is to prevent abuse, protect against denial-of-service (DoS) attacks, and ensure fair usage of API resources. By imposing rate limits on the APIs, the API providers can manage the server load, maintain the server availability and protect against the unpredicted high demand. We can use different rate limiting algorithms to implement this. Two most popular rate limiting algorithms are Token Bucket and Leaky Bucket. To indicate the overloaded requests to the consumer, we can use different ways. Mainly we can use Response code 429 and rate limit headers to convey the status to the consumer.


5. Server Accessibility
   When we deploy the APIs to a server or a cluster of servers, we have to make sure that we are exposing only the minimum requirements as possible. For example, If we have an API server with the database server, we can disable the public access to the database server. Also, we can disable the default SSH port access for the API server and use a custom port for SSH. We can allow access to the API Server only through our jump/bastion server with the custom SSH port. This is just a single example. Following the available standards, best practices, frameworks and guidelines will help us to secure our servers from such unintended access and serve our consumers smoothly.


6. Monitoring
   Monitoring plays a major role related to API security. Effective monitoring helps the API providers to detect and respond/react to security incidents and make sure the availability and performance of the APIs. Also, the monitoring provides insights about the potential threats and vulnerabilities. Key aspects of monitoring in API security best practices are logging and auditing, real-time traffic analysis, rate limit monitoring, resource usage, performance monitoring and of course there are many more. This way we can do a lot of adjustments and tuning for the deployment to make the APIs highly secured and continuously available for the consumers.

API Testing

Testing is a major requirement in any software development process as it gives us numerous advantages to bring our product to the production grade. Some of the advantages of testing are:

• Verification and validation of business requirements
• Early detection of issues
• Performance and reliability
• Security
• Compatibility and compliance

There are different types of testing methodologies available to achieve different objectives. But we will be covering a few of them. But still it is better to have more testing to make sure the product is reaching the required expectations.

1. Unit Testing
   The API developers should have implemented an adequate number of unit tests for each APIs to make sure the APIs are functioning properly. Usually we implement unit tests to validate the different scenarios of the business requirement to make sure the product is working as expected. We can integrate the unit testing with CI process to make sure that they run before the integration of new changes. That will make sure we do not have any breakable changes.


2. Integration Testing
   Integration testing involves testing the interactions between different components or systems. For APIs, this means validating that different API endpoints work together as intended and that data is exchanged correctly.


3. Load Testing
   Load testing assesses how well an API performs under a specific load or traffic volume. It helps identify performance bottlenecks, response times, and overall system scalability.


4. Stress Testing
   Stress testing involves testing the API under extreme conditions, such as high traffic, to determine its stability and behavior under stress. This type of testing helps identify the API's breaking points and potential failure modes. These tests specially help us to understand the proof against the DoS and DDoS attacks.


5. Security Testing
   Security testing focuses on identifying vulnerabilities and ensuring that the API is resistant to security threats. This includes testing for common security issues such as injection attacks, authentication and authorization issues, and data exposure risks. Other than the above-mentioned tests, we still have different types of testing that should be carried out to make sure the APIs are satisfying our business needs. Some of such testing methodologies are regression testing, end-to-end testing, smoke testing, automated testing.

API Contracts and Documentation

Nowadays we have different types of software development methodologies available. One of them is the API Design First approach. API Design First helps to define the API Contract first before starting the other implementations. This will help the stakeholders to define the API requirements including the security requirements in advance. This will lead to defining a robust API contract based on the agreement of stakeholders. Then the development teams of each party can start work on their functionality independently based on the API contract defined.

Defining the API contracts and doing the API documentation gives numerous advantages. Both API providers and API consumers have the advantages with the use of API contracts and documentation

• Clarity and understanding
• Ease of onboarding and reduce support burden
• Versioning support
• Developer engagement
• Consistency across teams
• Clear integration guidelines
• Time and resource saving

API documentation can be done in different ways. The most popular and standard way is to define the HTTP APIs using the Open API Specification. Open API Specification is commonly recognized everywhere as an API documentation standard for the HTTP APIs. Open API Specification has the capability to define our API endpoints in a properly organized way. It also allows us to define the servers, security schemes, reusable components and many more. There are different tools developed to do such API documentation using Open API Specification.

API Documentation with XAPI

XAPI is a great tool that supports defining API documentation with full support for Open API Specification 3.1. XAPI contains a set of rich features to make your process smoothen and create a great API contract as you need. Reviewing and commenting on the API spec, testing the APIs with remote servers, persisting and managing the APIs using the XAPIHub, testing the APIs, managing your APIs with your team, managing and tracking the changes of the APIs, using a kanban board to manage your API tasks are some of the greatest features available there. If you would like to have a look at this, simply go to the XAPI official site from here. The XAPI gives you everything you need to design your API spec properly in a better way in one hood.

Conclusion

As the APIs are the most common communication bridge with different types of systems and audiences, it is the responsibility of the API providers to design the APIs with standard API design principles and with the best practices. Security is a main concern with regards to APIs nowadays because with the heavy use of APIs we have counter attacks also increased proportionally or exponentially. So, it is always required to follow the security best practices when designing, developing, deploying and testing the APIs to minimize the impact that could potentially receive. A better design of an API Contract will save you from numerous problems while giving you a lot of advantages. It is better to use a standard way to design the API contracts for your API needs. The Open API Specification is such a great standard that most of the developers follow to design their HTTP based APIs. It is always better to use Open API Specification standards supported tools like XAPI to use for your design as it gives more than just API design.

SB Karunarathne

Tech Lead/Team Lead at X-Venture