Get Some Rest! A Full API Stack

Editor's Note: The following is an article written for and published in DZone's 2024 Trend Report, Modern API Management: Connecting Data-Driven Architectures Alongside AI, Automation, and Microservices.

REST APIs have become the standard for communication between applications on the web. Based on simple yet powerful principles, REST APIs offer a standardized yet flexible approach to the design, development, and consumption of programming interfaces. By adopting a client-server architecture and making appropriate use of HTTP methods, REST APIs enable smooth, efficient integration of distributed systems.

Becoming a standard, the API ecosystem has grown much richer in recent years and is increasingly integrated into the DevOps ecosystem. It has been infused with agility, CI/CD, and FinOps, and continues to develop by itself. In this article, we're going to compile these new practices and tools to give you a large overview of what an "API approach" can do.

API Design and Documentation

The API design and documentation stage is crucial, as it defines the basis for all subsequent development. For this reason, it is essential to use methodologies such as domain-driven design (DDD), event storming, and API goals canvas — which represents what, who, how, inputs, outputs, and goals — to understand business needs and identify relevant domains and the objectives of the APIs to be developed. These workshops enable businesses and dev teams to work together and define API objectives and interactions between different business domains.

Figure 1. Designing APIs

When designing and documenting APIs, it's essential to take into account the fundamental principles of REST APIs. This includes identifying resources and representing them using meaningful URLs, making appropriate use of HTTP methods for CRUD (Create, Read, Update, Delete) operations, and managing resource states in a stateless way. By adopting a resource-oriented approach, development teams can design REST APIs that are intuitive and easy to use for client developers. REST API documentation should highlight available endpoints, supported methods, accepted and returned data formats, and any security or pagination constraints.

As such, the REST principles do not exclude the freedom to make a number of choices, such as the choice of naming conventions. For a compilation of these best practices, you can read my last Refcard, API Integration Patterns.

In this stage, API style books play a crucial role. It gives design guidelines and standards to ensure the consistency and quality of the APIs developed. These style books define rules on aspects such as URI structure, HTTP methods to be used, data formats, error handling, and so on. They serve as a common reference for all teams working on API projects within the organization. Stoplight and SwaggerHub are commonly used, but a simple Wiki tool could be enough.

Data model libraries complete this phase by providing reusable data models, which define the standard data structures used in APIs. Data model libraries include JSON schemas, database definitions, object models, and more. They facilitate development by providing ready-to-use assets, reducing errors, and speeding up development. Commonly used tools include Apicurio and Stoplight.

A workflow API's description is often missing from the APIs we discover on API portals. Questions arise such as:

• How do I chain API calls? 
• How do I describe the sequence of calls? With a drawing? With text in the API description? 
• How do I make it readable and regularly updated by the person who knows the API best (i.e., the developer)?

It could still be a pain to understand the sequence of API calls. However, this is often covered by the additional documentation that can be provided on an API portal. Yet at the same time, this was decoupled from the code supplied by the developers. The OpenAPI Specification allows you to define links and callbacks, but it is quickly limited to explaining things properly. This is why the OpenAPI Workflows Specification has recently appeared, allowing API workflows to be defined. In this specification, the steps are always described in JSON, which, in turn, allows a schema to be generated to explain the sequence of calls.

If you want to describe your workflows from OpenAPI specifications, you can use Swagger Editor or SwaggerHub. And you can use Swagger to UML or openapi-to-plantuml. If you want to begin by designing sequence diagrams, you can use PlantUml or LucidChart, for instance.

There is no unique toolchain that fits all needs; you have to first know if you prefer a top-down or bottom-up approach. Tools such as Stoplight Studio combined with Redocly are commonly known for handling these topics — Apicurio as well. They can be used for API design, enabling teams to easily create and visualize OpenAPI specifications using a user-friendly interface. These specifications can then be used to automatically generate interactive documentation, ensuring that documentation is always up to date and consistent with API specifications.

API Development

Once the API specifications have been defined, the next step is to develop the APIs following the guidelines and models established during the design phase. Agile software development methods, effective collaboration, and version management are must-have practices to ensure good and fast developments.

Figure 2. Building APIs

For versioning, teams use version control systems such as Git or GitHub to manage API source code. Version control enables seamless collaboration between developers and ensures full traceability of API changes over time.

During development, the quality of the API specification can be checked using linting tools. These tools can check:

• Syntax and structure of the code
• Compliance with coding standards and naming conventions
• Correct use of libraries and frameworks
• Presence of dead or redundant code
• Potential security problems

Swagger-Lint and Apicurio Studio or Stoplight can be used to carry out these and other linting checks, but these checks can be made into a CI/CD toolchain (more info to come in the API Lifecycle Management section).

Automation plays a crucial role in this stage, enabling unit, security, and load tests to run seamlessly throughout the development process. Postman and Newman are often used to automate API testing to ensure quality and security requirements, but other solutions exist like REST Assured, Karate Labs, and K6.

Development frameworks supporting API REST development are very common, and the most popular ones include Express.js with Node.js, Spring Boot, and Meteor. Most of the popular frameworks support HTTP, so it should not be a complicated action to choose. API capacities are a must when you choose a framework, but they are not the only ones. Developers will build your stack, so you'll need frameworks that are both appreciated by your devs and relevant to other technical challenges you'll have to tackle.

And we have to speak about mock prototyping! It's something that could unlock developers' inter-dependency to propose a Mock API whenever you target internal or external developers. This is generally based on the OpenAPI description of your API and is often taken into account by API management portals. There are also dedicated OSS projects such as MockServer or WireMock.

API Security

API security is a major concern in API development and management. It is essential to implement authentication, authorization, and data encryption mechanisms to protect APIs against attacks and privacy violations. API keys, OAuth 2.0, and OpenID Connect are the three protocols to know:

• API keys are still widely used for API access due to their ease and low overhead. They are a unique set of characters sent as a pair, a user, and a secret, and should be stored securely like passwords.
• OAuth 2.0 is a token-based authentication method involving three actors: the user, the integrating application (typically your API gateway), and the target application. The user grants the application access to the service provider through an exchange of tokens via the OAuth endpoint. OAuth is preferred for its granular access control and time-based limits.
• OpenID Connect is a standardization of OAuth 2.0 that adds normalized third-party identification and user identity. It is recommended for fine-grained authorization controls and managing multiple identity providers, though not all API providers require it.

In addition to that, solutions such as Keycloak can be deployed to provide centralized management of identity and API access. Alternatives of Keycloak include OAuth2 Proxy, Gluu Server, WSO2 Identity Server, and Apache Syncope. But just talking about tools and protocols would not be enough to cover API security.

Contrary to what we sometimes read, a front-end web application firewall (WAF) implementing the OWASP rules will prevent many problems. And what certainly requires a dedicated DZone Refcard, like Getting Started With DevSecOps, a comprehensive DevSecOps approach will greatly reduce the risks.

However, automated security testing is also essential to guarantee API robustness against attacks. OSS tools such as ZAP can be used to tackle automated security tests, identifying potential vulnerabilities in APIs and enabling them to be corrected before they can be exploited by attackers.

API Lifecycle Management

Once APIs have been developed, they need to be deployed and managed efficiently throughout their lifecycle. This involves version management, deployment management, performance monitoring, and ensuring API availability and reliability. API management platforms include, but are not limited to, Gravitee, Tyk, WSO2 API Manager, Google Cloud Apigee, and Amazon API Gateway are used for API deployment, version management, and monitoring. These platforms offer advanced features such as caching, rate limiting, API security, and quota management. Clearly, these are must-haves if you want to be able to scale.

Figure 3. Running APIs

To ensure compliance with standards and guidelines established during the design phase, tools such as Stoplight's Spectral are used to perform a linting analysis of OpenAPI specifications, identifying potential problems and ensuring API consistency with design standards.

And of course, at the end of the chain, you need to document your API. Tools exist to automate many tasks, such as Redocly, which generates interactive documentation from the OpenAPI Specification. The added benefit is that you ensure that your documentation is constantly up to date and always simple and readable for everyone, developers and business analysts alike.

API management also involves continuous monitoring of API performance, availability, and security, as well as the timely implementation of patches and updates to ensure their smooth operation.

API Analysis and Monitoring

Analysis and monitoring of APIs are essential to ensure API performance, reliability, and availability. It is important to monitor API performance in real time, collect data on API usage, and detect potential problems early. The ELK Stack (Elasticsearch, Logstash, Kibana) is often used to collect, store, and analyze API access logs for monitoring performance and detecting errors. OpenTelemetry is also used in many use cases and is a must-have if you want to monitor end-to-end processes, especially ones that include an API.

Regarding API performance metrics, Prometheus and Grafana are commonly used in real time, giving much information on usage trends, bottlenecks, and performance problems.

FinOps and Run Management

Finally, once APIs are deployed and running, it's important to optimize operating costs and monitor cloud infrastructure expenses. FinOps aims to optimize infrastructure costs by adopting practices such as resource optimization, cost forecasting, and budget management.

Cloud cost monitoring tools such as AWS Cost Explorer, Google Cloud Billing, and Azure Cost Management are used to track and manage cloud infrastructure spend, keeping operating costs under control and optimizing API spend. However, in a hybrid cloud world, we could consider open-source solutions like Cloud Custodian, OpenCost, and CloudCheckr.

Conclusion 

Obviously, you don't need to put all this in place right away to start your API journey. You have to first think about how you want to work and what your priorities are. Maybe you should prioritize design tools, like linting tools, or define your API style book and API design tool. Of course, prioritize tools that are commonly used — there's no wheel to reinvent! In fact, I'd say implement everything that is at the beginning of this toolchain because it will be easier to change after.

I hope all these points in mind will enable you to get started serenely while prioritizing your own API needs.

This is an excerpt from DZone's 2024 Trend Report, Modern API Management: Connecting Data-Driven Architectures Alongside AI, Automation, and Microservices.

Read the Free Report