In this lesson, the following topics are discussed:
- What is an API First Approach?
- What are APIs?
- Types of APIs.
- Interface types mainly used in SAP.
- How to design APIs with description languages.
- Fulfill the contract between API Provider and API Consumer.
What is an API First Approach?
The API First Approach is an approach to software design that focuses on the API to create applications that can be easily connected to each other. API First creates ecosystems of applications that are modular, reusable, and extensible, such as Lego bricks.
An API First Approach means that your APIs are treated as first class citizens. Everything revolves around the end product being used by mobile devices and client applications. An API First approach involves developing APIs that are consistent and reusable. This is achieved by using an API description language.
Explanation:
- API Provider
- An API provider provides an interface with technical features (No. 1). Symbolically, this is shown in this picture with the ball- or lollipop notation. This interface can be consumed by a service (No. 5). The representation corresponds to the socket notation (No. 2). The service acts in the role of the API consumer.
- API Consumer
- The API Consumer requires an interface (No. 3). The representation corresponds to the socket notation (No. 4). In this case, the API provider is the service (No. 5). The presentation is again made with the ball- or lollipop notation.
Find more information at:
What are APIs ?
API stands for Application Programming Interface. An API specifies the operations as well as inputs and outputs of a software component. It defines functionalities that are independent of their respective implementations, so that these implementations can vary without affecting the user of the API.
Types of APIs
In the literature, there are many overviews of different types of APIs. Below is a simple overview of the APIs that we need to understand for this course.
Here, four different APIs are defined under the superset of APIs, based on their use.
- Databased APIs
- These are intended for file exchange between systems. Files can be, for example, configuration files.
- Object-orientated APIs
- These are used in object-oriented programming languages to define the communication of the classes with each other.
- Remote APIs (No. 1)
- This includes today's important web APIS, such as REST and SOAP APIs. REST itself is not a protocol but a software architectural style.
- Messaging APIs (No. 2)
These are mainly asynchronous APIs that send events based on events. These are used in Event Driven architectures.
Interface Types Mainly Used in SAP
Technically, a few protocols have been agreed upon. The following overview figure shows the APIs with their relationship to each other.
These are at SAP:
- REST APIs, like RESTful HTTP APIs:
- OData 2.0
- OData 4.0, both like SAP Graph.
- Remote APIs, like SOAP APIs.
- Messaging APIs, like Event APIs.
The presentation formats are either JSON or XML.
How to Design APIs With Description Languages
SOAP based APIs are described with Web Services Description Language (WSDL). It is an XML-based interface description language that is used for describing the functionality offered by a web service.
You will find more information about WSDL here: Web Services Description Language
REST-based APIs can be created with the following main description languages:
- RAML
- OpenAPI
- RAML
RAML is a YAML-based language for describing RESTful APIs.
You will find more information about RAML here: https://raml.org/
- OpenAPI
The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing RESTful web services.
You will find more information about OpenAPI here: openapis.org
The OpenAPI specification is used in API management.
Fulfill the Contract Between API Provider and API Consumer
The description in RAML or OpenAPI is the contract between API Provider and API Consumer. The API must be implemented along this contract.
Two cases are possible:
- Implementation - first approach
- The implementation is first created on the part of the API provider. The description (contract) is then generated automatically. This is used by the Consumer API.
- Contract - first approach
The API description is first created with RAML or OpenAPI. Generators automatically create the rudimentary implementation for the API provider and -consumer. These rudimentary implementations in different programming languages and concepts must then be fully implemented.
Summary
In an API First Approach, only the provided APIs are of interest. By using standardized communication protocols and concepts, such as REST and OData, almost any use case can be mapped across all borders. Communication takes place between an API provider who has the interface available and the API consumer who consumes this interface. The APIs are described with standardized description languages, such as RAML or OpenAPI. The implementation can be created at first at the API provider and then at the description (implementation - first approach based on it) or the other way round by first creating the description and then automatically creating server and client stubs from it (Contract - first approach). We see that SOAP APIs, OData 2.0 and 4.0 APIs as well as SAP Graph play the leading role in the SAP universe.
