How to build an API

What is an API?

What is an API, and what are the guidelines for successfully building one? An application programming interface (API) is a set of programming functions, tools, and protocols that allow external applications to access and interact with either the features or the data of a platform, operating system, application, or service. Effective APIs open the door to greater data sharing and collaboration, creating an ecosystem where different pieces of software can communicate with each other to deliver business functionality. APIs are a core component of modern applications and of cloud native, microservices-based architectures; they create the main channels for different services to communicate with each other and deliver modern experiences.

Designing, developing, and distributing successful APIs requires leveraging a range of best practices. By adhering to these best practices, the process ensures secure access and easy usage by developers and applications, alike. These best practices include:

Simple and elegant design that ensures that developers of varying skill sets and experience can use the APIs
High levels of security to limit access to data, as required
Lean design principles to ensure that accessing the API won't bog down either the source or the external application
Related services to ensure governance, security, and usage monitoring for existing APIs

How to develop an API from scratch

Building an API depends largely on specific factors regarding both the source and the external application(s) that will be interfacing with this source. Here are some questions to ask when planning your API development process.

What are your goals?
For any type of project, the best place to start is always the big picture: defining and understanding your goals. The purpose of your API is the guiding light on this project. What information will be exchanged through the API? How will it be used or presented? Other elements to factor in include understanding your application's target audience and their needs.

What are your limitations?
The flip side of your project goals are project limitations. Applying a practical lens to development is a necessary step, so you should have a good understanding of your own resource and schedule limitations. Another factor to consider: any technical limitations, such as security concerns, impact on hardware resources, and performance demands should scalability be a concern.

What is your architecture?
When it comes to designing an API from scratch, developers have numerous starting points to choose from. Python, Java, JavaScript, C#, and other languages are all capable choices for developing your API. Other factors to build into your design considerations include usability, scalability (coupled with resource needs), and security. This final one is particularly important, as APIs act as bridges between applications. In doing so, both sides must have their data properly protected. An API with security vulnerabilities is open to exploits, such as code injection and data exposure.

With these big-picture questions, guidelines can be defined and developers can dive deeper into the process of building an API from scratch.

SOAP vs. REST APIs

One of the key decisions when designing an API comes down to how the application will access web services. Simple software architectural styles object access protocol (SOAP) and representational state transfer (REST) can both be effective paths for designing an API. Both offer pros and cons, and the one that works best for a project depends on the situation and context of usage. In general, web services will support either SOAP or REST, so deciding on the web service for your API may very well be defined by whether SOAP or REST works better for your goals.

What is SOAP?
SOAP is an XML-based protocol originally designed by Microsoft. Built around a set of rules, SOAP creates standards in messaging that have supported numerous expansions (WS-coordination and WS-security), automation, and built-in error handling. SOAP works best in a distributed environment, but its reliance on XML structure can make the code overly complex.

What is REST?
REST was developed as a simpler, more lightweight alternative to SOAP that operates on a point-to-point level. As a software architectural style built specifically for efficient scalability, REST offers a series of standardized constraints that minimize processing while delivering flexibility. REST's fast response minimizes latency across various output message formats used by applications, including JSON and CSV.

Should you use REST or SOAP for your API?
Which is the best standard for your application? It depends on your needs. For most cases where the application is enabling simple, user-facing messages, such as shared media or output from a database query, REST APIs are ideal. SOAP has a steeper learning and usage curve, but this inherent complexity makes it capable of handling more complicated transactions, such as secure payments.

Choosing your API design tools

The nuts and bolts of building an API vary depending on the tools chosen by the development team. Oracle Cloud Infrastructure (OCI)’s API solutions enable you to easily design and develop APIs with a full toolkit that enables fast prototyping and validation, based on OpenAPI specifications. With OCI, users can access either API Blueprint or Swagger to design their APIs. In addition, APIs can be built from scratch or from templates to accelerate the development process.

Let's take a closer look at the API development process on OCI. For this example, we will create an API resource (optionally with an API description created from an uploaded API description file) using the OCI console. Follow the steps yourself by signing up for a free OCI account.

In the console, open the navigation menu and click Developer Services. Under API Management, click Gateways.
On the APIs page, click Create API Resource and specify its Name. Upload an API Description File (containing an API description in a supported language), and Tags.
Click Create to create the new API resource.
Write the backend code. Using your preferred programming language and framework, create the backend code that will power your API. This can be an iterative process that includes other collaborators.
Test the backend code. Oracle’s API development service includes various tools to test both locally and through various continuous integration (CI) services.
Deploy. Launch the API and make it accessible to developer ecosystems, partners, customers, and internal developers. Oracle API Gateway enables usage monitoring and management of API connections, security, and governance.

For a more in-depth look at API development using Oracle’s cloud-based API solution, check out the Oracle API developer’s guide (PDF).

Best practices for testing APIs

Thorough testing of your API is a crucial step to ensure a smooth launch and ongoing operations. To help you deploy APIs that will meet your business needs, here’s a short list of effective API best practices to follow:

Validate the code using an API smoke test (a bare-bones test validates that the basic functionality of your API is working). The smoke test should check for repeatable errors.
Use realistic data under conditions similar to your production environment. Working with data that isn’t reflective of real-world use cases will only prolong your ability to troubleshoot different scenarios and may produce unreliable tests. So testing should replicate a real-world scenario as closely as possible.
Perform both positive and negative testing. Because testing requires a full spectrum of expected results and usage scenarios, developers must factor for both positive (expected functional outcome) and negative (planned errors creating unexpected outcomes) testing as part of their plan.
Use comprehensive tracking of API responses for transparent results. Testing can be a long and arduous process, and the impulse to discard test results is natural when massive volumes exist. However, diligently logging this data ensures a clear record of functionality, behavior, test results, and effectiveness.
Check for both security and performance. Functionality is obviously key, but once testing has been proven to work, it’s just as important to check for security (data and access risks) and performance (resource usage, scaling, and efficient processing).

Ready to build and test your API? Try Oracle Cloud Infrastructure API management services for free to experience the complete API lifecycle management solution.