API DESIGN FIRST

Written by Antoine Pagbe Baleba and Marcellin NDIYAE

Implementing a software component is often based on the “Code-First” approach, particularly for “Domain-Driven-Design”, this approach is very development-oriented and ignores the business need. However, current best practices suggest that the component be “Designed” before any implementation; this is the “Design-first” approach. This approach proposes to define the component contract as a priority based on a well-identified need. In the API case, it is a question of carrying out the OpenAPI Specification before writing the code.

In a Design First approach, the objective is to express the business functionalities, identify consumers, decline the use cases, determine the exposed data, and produce the API contract before implementation.

So, what are the steps to follow to “design” an API?

First, we must identify consumers, define the needs to be covered and document them in use-cases.

As in any product, the design process begins with identifying the features of the software component to be implemented. These features can be derived from the existing ones. For example, data that offers functionalities already available within the Information system that we would like to enrich or made available to customers or external partners.

For an API to be easily understandable and easy to use, you should design it from the consumer’s perspective, not the provider’. It is what is called the consumer First approach, which complements the more global Design First approach. Thus, it becomes crucial to identify known consumers; they may be internal to the company. But it is also essential to imagine potential, unknown consumers; this can be the case for a public API. We can then imagine their expectations and supplement the needs accordingly.

As you have identified consumers, it becomes possible to define their action, how they can perform them, what they need to achieve them, especially what they receive in return. This step helps to understand better the expectations of consumers regarding the API to be built. It also helps to collect all the needs. You can decline the business need in uses cases, making it possible to refine and clarify the API’s purpose. Hence, you define the name of the API and its description. This description can already include the use cases that will benefit the “API developers”.

Then define the API Interface

During interface definition workshops, the following points serve to:

· Define the attributes of the object to be exposed, as well as their formats,

· Identify security requirements,

· Define the resources to be exposed and the corresponding actions,

· Constitute the input data and specify the source,

· Define business rules

· Define the output data and its formats

· Specify error codes and associated messages:

· Choose the technology and implementation protocols.

It would be best if you took the business object from the company’s data repository. The enterprise repository defines the business object, all its attributes, and renditions. What guarantees the uniqueness and consistency of the component you supply. Neither the structure of the object nor the formats of the attributes should depend on the vision of the API provider.

An API is not always accessible by everyone; it all depends on the sensitivity of the exposed data. Thus, an API can be public, restricted, or private, on all or part of its exposed attributes. To properly define the visibility of the API, the “Design” must take into account the security requirements set by cybersecurity.

The actions to be carried out by consumers stem from the use cases. They are available in the form of endpoints and associated protocols. Depending on the context, the API can offer access in Synchronous and/or asynchronously mode. The input and output parameters must be defined, described, and their format specified.

User experience is a critical element of adopting an API. It is therefore essential to make the consumer sufficiently autonomous. Thus, error handling must be rigorous. In addition, the return codes and the messages that guide them must be well documented and in line with the standards used. In particular, HTTP codes and returned messages must be consistent with the standard.

When “Designing” the API, what are the mistakes to avoid absolutely to guarantee a better user experience?

One of the mistakes to avoid is to “design” the API from the provider’s point of view. Typically, the provider’s point of view can influence the choice of the technology to be used, the naming of attributes, the programming language. Sometimes the structure and model and database structures determine the naming and API attributes types. For example, you cannot expose SAP fields as encoded in a DB instance as they are.

You cannot choose the technology and programming language based on the API provider. For example, they are likely to complicate the understanding of the API or be unsuitable for target uses. Such a design can be a hindrance to API adoption.

The API would therefore be either poorly consumed, little consumed or not consumed at all.

Finally, document the API

API reference documentation: OpenAPI Specification

The Open API specification is the deliverable provided at the end of the API design. It would be best if you did not generate it but built it using Design tools such as Postman, Swagger Editor etc. In the TotalEnergies context, an Open API specification should contain the following (the complete list is available on About Swagger Specification | Documentation | Swagger ):

· info:

the info object allows you to give more information about the API purpose. It must contain at least the following attributes: the title, the description, and the contact detail of the PAI owner, which is the first point of contact inter of support.

· paths:

Paths are exposed endpoints, and associated HTTP operations to manipulate these paths, including GET, POST, PUT, DELETE… Therefore, it is recommended to make the API version appear in the API base path.

· components:

API operations can have standard input parameters or responses in terms of structure; to avoid code duplication, you must define common data structures in an object called a “component” and reference it where necessary.

· security:

The OpenAPI Specification uses the term “security scheme” for authorization and authorization. For example, the OpenAPI Specification version 3 provides the following “schemes”: HTTP authentication, API keys, OAuth 2, OpenID Connect.

At the TotalEnergies Digital Factory, OAuth 2 is the mandatory “security scheme”, the use of API keys is subject to validation by cybersecurity.

· Tags:

The Tag object contains metadata applied to the operations of an API; thus, similar functions can be grouped in the form of TAG, in particular by type of data manipulated, by exposed functionality which facilitates their accessibility via a search.

Tags are also applicable at the API level itself; in this case. For example, you can group APIs according to the business branch, the type of data handled, or the visibility.

For more details, see the following link: https://swagger.io/docs/specification

Who should be involved in the Design of the API?

One of the critical success factors of the “design” of an API is the pooling of skills that will interact with this component under the coordination of the team in charge of API governance. In addition to the API Owner and API Designer:

· POs (Product Owner)

· DevOps teams

· Security

· Architects

· Business teams

The teamwork carried out by this working group during design workshops makes it possible to consider all the technical and functional constraints allowing to “design” a quality, intuitive and easy-to-use API.

A poorly “Designed” API can be poorly consumed, less consumed, or not consumed at all. Designing a good API requires ignoring the organization, the technology of the application in place, and the existing data structure.

The Open API Specification is the deliverable that starts the API implementation phase. Since the API is implemented, it can be exposed on an API management platform to make it visible.

In the following article, we will discuss the requirements of a well-exposed API. Among other things, we will include specifying all the documentation complementary to the OpenAPI Specification and optimizing the adoption of your APIs.