Building APIs the right way is important. It's one of the API basics you need to know.
We are in the midst of an API revolution. Many business leaders are looking to APIs for achieving digital transformation in the enterprise. Given the amazing growth and diversity of APIs, there are surprisingly few easy-to-read resources on how to get started.
Below, we describe the best practices for building an API. We discuss specific technology examples as well as broad business-level issues that affect API development.
What Does It Mean to Build an API?
Building APIs means created a set of established protocols for external applications to interact with your application.
It's important to have an API strategy and roadmap in place before beginning development. From this roadmap you can structure a development team to deliver the next API — or the next version of an existing API.
So, how is an API best designed and built? What goals must be achieved in order for your organization to confirm that it has built the API according to best practices?
Goals of Building APIs
Here are four key goals:
- Understand and clearly articulate the detailed requirements for the API. Make sure there is agreement between key players before development starts.
- Separate functional from non-functional requirements and develop only to the functional requirements.
- Iterate through the API development process.
- Utilize an existing platform investment.
Related Blog >> How to Define API Requirements
APIs are lightweight, self-describing, and agile interfaces that lend themselves to easy access and reuse. You must keep this in mind when designing and building your APIs. That being said, the process of creating APIs is comparable to that required for any other software development projects.
Back to topEnterprise API Management, Defined
Building APIs is just one aspect of API management. Learn how to go from building APIs to building an API and digital transformation strategy in this white paper.
Guidelines to Apply to All API Build Stages
The following guidelines apply to all API build stages.
1. Start Simple
Begin with a short section of the already defined specification that covers the functionality to be built. Bear in mind that you should stay flexible about your API definition, even if it means omitting detail.
2. Code With Confidence
Code the API as you become more confident that you are moving in the right direction
3. Be Realistic
Be realistic when you build APIs. Keep the following in mind:
- You can’t please every stakeholder.
- Many API designs suffer from excessive constraints.
- You will definitely make mistakes.
- The real world will reveal weaknesses and you will be able to correct them.
- Your API will evolve.
Back to topRelated Blog >> What Is API Design?
How to Build APIs
Here are the key steps to building APIs.
1. Use Stubbed Out Code
Serve the resources and collections with stubbed out code to get started.
This will help with unit tests and allow for parallel development. If the API is supporting a web client, a stubbed out backend will greatly speed up UI development. Conversely, if you are composing an aggregate API using a composition tool or mashup engine, then create it one operation at a time.
2. Write to the API Frequently
Write to the API frequently, starting early in the process.
Even if the API is not complete, start programming to it. The learning from this process will save you time later as you avoid unnecessary implementation issues. This applies to either approach, both custom code and mashup.
3. Add Resource Relationships For HATEOAS
Include resource relationships to support HATEOAS.
HATEOAS stands for "Hypermedia As The Engine Of Application State." This is referring to the same state as Representational State Transfer (REST API).
In short, HATEOAS means that when a resource representation is returned as a result of an API request. The representation includes the information that defines that resource. It also contains all the valid relationships that the resource has with other resources for that state. And it includes the valid states that the resource could transition to.
In other words the resource is self-describing.
4. Determine a Strategy For Data
Determine a strategy for retrieving and updating partial data.
APIs are lightweight. They need to be because of the latency introduced by the fact that they live in the internet. Because of this, it is not often sensible to return every resource that meets the requirements of the API request.
An API must have a designed and consistent scheme to allow the app to request a partial set of satisfying resources. Consequently, the modification of this result set needs also to be supported. Proper adherence to HATEOAS should resolve this requirement.
5. Add Validation
Once the following steps have been implemented successfully (remember this can be partially – per resource – as per the general guidelines). Validate any resource that is the subject of a PUT, POST, or DELETE call (usually JSON, but may also be XML). Use an HTTP error code to define and transfer exception information. This will enable you to handle those exceptions on the client side.
6. Build an API Client
When it comes to building your API client, there are again some critical areas you’ll want to focus on.
Keep It Simple
Use the technology you are most familiar with that supports the API technology set. This could even be a tool such as SOAPUI. This client will become invaluable in both development and testing.
Make Sure It Can Be Automated For Testing
This is an important point. Once it can be automated, it can be incorporated into the API build and test process. This will ensure consistent delivery of new versions of the API.
7. Add the Nonfunctional Requirements
Ensure you account for the following nonfunctional requirements:
- Mime type.
- Security – authentication and authorization.
- Caching.
- Paging
- Load balancing.
- Failover.
- Disaster recovery.
- Logging/auditing.
This list is not exhaustive. Please be aware that it is not meant that you should code the solution for these requirements.
If you have a good API platform available to your organization, then it should supply the components to support the solutions declaratively. Maximized reuse and flexibility are achieved when nonfunctional requirements are supported by this mechanism. This being said, adding the support for the nonfunctional requirements at this late stage does not imply that they are less important than the other steps mentioned.
It’s just more practical to ensure that the required functionality is supported before adding the requisite complications of the nonfunctional support.
Apart from security, there are two broad types of non-functional requirements that this list represents. The first is performance, and the second is resilience. Both of these types are solved by a combination of network architecture and API platform. The platform gives the ability to support load balancing, failover, paging, logging and auditing, and disaster recovery, while the network architecture provides the caching, load balancing, and failover.
Notice that load balancing and failover are mentioned under both categories. This is because they should be supported by both. Your organization has the choice of using one over the other, or in concert with each other. The ultimate solution is dependent on your organization’s needs and capabilities.
8. Standardize Content
Earlier, we covered requirements elicitation for business and technical regulatory requirements. Here is where those requirements are defined in the build to support these requirements.
First, match these to the capabilities of your API platform to ensure that it gives you the maximum coverage possible and then incorporate the remaining nonfunctional requirements into your API design. A good API platform should support as many of the nonfunctional capabilities as possible.
Technical Environment
Your API will face constraints that flow from its technical environment. These include:
- Server functionality.
- Server capacity.
- Client technology.
- Security.
The next consideration is network capability and design. This will need to address the following:
- Scalability.
- High availability.
- Disaster recovery.
The amount of traffic that will flow through the API will help identify the required server capacity and functionality. A dedicated API server may be required in order to provide adequate capacity and to isolate the core business processes. In addition, the type of user should be well understood and documented during the charting of technical environment constraints. For example, your user base could include anonymous users, registered clients, or a combination of both.
Back to topBuilding APIs with Akana
Akana is one of the best API platforms for building APIs.
With Akana, you can build APIs, scale them in a developer portal, and monitor their usage and functionality — all from a single interface. In addition, Akana comes with complete security and full API lifecycle management.
We can support your API monetization strategy no matter your industry or scale. We have helped dozens of clients across multiple industries gain scale and monetization in their API management. This includes large global banks monetizing OAuth-secure APIs, to farm equipment manufacturers monetizing vehicle APIs that collect crop data.
No matter your challenge or IT environment, Akana can support a full-scale API strategy.
Sign up for free 6-month trial to get started with Akana.
Start Free Trial ▶️ Watch Demo First
👉 Become an Expert
Explore additional resources:
This blog was originally published as a white paper in 2015. It has since been updated for accuracy and comprehensiveness.