Anyone involved in the planning, design and development of API interfaces will sooner or later have to deal with the API definition and one of the popular description languages. A good API is characterized above all by positive quality characteristics. First and foremost, this includes clear consistency, the easiest possible usability and a suitable abstraction. The importance of a helpful documentation should be ensured from the beginning and must never be underestimated. As soon as the API is to be made available to other developers, it is imperative to document as detailed and comprehensive an API definition and description as possible. A powerful Web API is only successful if its structure is well represented. Technical specifications such as end points offered, HTTP methods and parameters used, and how requests should look are essential. All these specifications ensure good usability and, if formulated appropriately, also support automatic code generation. The description language used to create an API definition is left to the developer. Here we highlight the most common languages like Open API, Swagger and RAML. Open API Under the leadership of the Linux Foundation, a special working group called the "Open-API Initiative" was founded in 2015. At the same time, Swagger was taken over by SmartBear - the tool manufacturer of the well-known and respected SoapUI. Both steps led to the renaming of Swagger to the Open-API Specification (OAS) under the aspect of remaining manufacturer-neutral. In the meantime 26 members such as Adobe, SAP, PayPal, eBay, Google, MuleSoft and also Microsoft belong to it. The consistent further development takes place on GitHub and opens thereby the participation in the project to any interested party through issues or pull requests. In mid-2017, version 3.0 of Open-API was approved and published. Compared to the previous version 2.0, a clearer structure could be achieved especially on the top level of the hosts and security. Another big step forward was made in supporting the JSON scheme. Based on the formats JSON or YAML 1.2 different languages like Java, JScript, .Net, Ruby, Scala or Gitlab can be used. Also in Open-API the starting points Contract-/API-First or alternatively the program code via Code-First exist. A detailed description of Open API can be found in our practical article Open API Specification. Swagger The Swagger API project was launched by Tony Tam in 2011. In today’s highly networked business world, it is increasingly important to allow distributed applications to communicate with central servers via API interfaces. For a long time, APIs were preferably described using the WSDL (Web Service Description Language). Probably the biggest disadvantage is the technical implementation of REST interfaces. One of the biggest advantages of Swagger, however, is the language-neutral and machine-readable format, which is usually defined with JSON or YAML. In addition, it offers a powerful extension mechanism. Swagger also has the IDL (Interface Definition Language) for simplified programming of RESTful interfaces. In addition, Swagger supports both Code-First and Contract-/API-First development. Various tools such as the core library (swagger-core), the visualization interface (swagger-UI), a powerful editor (swagger-Editor) and the code generator (swagger-Codegen) make it easy to develop and test powerful interfaces. As part of the description Swagger Tooling can be used. Based on the source code, a complete documentation can be generated automatically. A much more detailed description of Swagger can be found in our article Swagger. RAML What started with Swagger as a quasi-standard for REST-based applications has been more clearly structured and extended with the Open-API specification. However, there is no standard for the description of a REST API, but SOAP-based Web services have always been described by WSDL documents. With RAML (RESTful API Modeling Language) another important tool for API First Development is now available. The requirement for a uniform description of REST API’s is not really new. An API definition usually includes the following contents such as entry points, resource paths, GET/PUT methods with parameters, business objects, types and error codes. Mulesoft’s developers summarized the necessity and advantages of the API definition in the modern RAML description language. They benefit greatly from many predecessors such as WADL and Swagger. An API description is provided in YAML file format. This makes it very easy to read due to its simplified notation, on the one hand, and on the other, even complex hierarchies can be represented very well. An accompanying documentation can also be given over several chapters. Query parameters can be defined for individual methods and can also be used as so-called "traits" in other methods. Details and possible applications for RAML can be found in our TECH article RAML. Conclusion The description languages listed here have a solid basis and many followers. Swagger is the quasi-standard for REST-based API definitions due to its wide distribution and tool support. RAML is a technically modern and lightweight description language that provides various tools for API modeling. The Open API Specification is based on Swagger and introduces clearer structures and meaningful extensions and will probably establish itself as the new standard in the long term.

The now high level of networking and digitization in business, industry, administration and the private sector also requires increasingly high-quality services and requirements for software structures. Data-based ecosystems and platforms now use complex and powerful API interfaces to meet business requirements. Open interfaces for the versatile applicability of data and information represent a central key position here. The more complex an interface must be designed, the more important an open and defined structure is. This is then documented with an appropriate description language. Open API provides developers with a modern and powerful API description language for their projects. Based on Swagger’s open source tools, which are already very successfully established on the market, the new Open-API project was founded in 2015 under the leadership of the Linux Foundation from the Open-API Initiative. This initiative currently has 26 active members, many of whom are big players. Here, renowned companies such as Microsoft, Google, SAP, Paypal, Adobe, Smartbear or MuleSoft can be found. This ensures a comprehensive compatibility and structure of the services provided and published. Version 3 has been available since 2017 for project planning and implementation of powerful APIs. One of the biggest advantages of Open-API is the comprehensive language support for Java, JScript, .Net, Ruby, Scala or Gitlab. These are all based on the formats of JSON or YAML 1.2 and thus provide very high compatibility. Further innovations can be found in the finally adapted and extended support of the JSON schema. In addition, innovations and restructurings have been introduced in the areas of security and hosts. The reuse of components was solved in a particularly convenient way. HTTP headers, requests, responses, parameters, callbacks, links, object schemes and examples can now be stored in a separate area. The core elements of Open API The requirements should already be clearly defined during the planning of an API. Here it is particularly important to deal with the core elements of functionality and later documentation. Every user of an API must be able to access the information of the used parameters, endpoints, return values and safety factors. This is the only way to ensure optimum and efficient use of the interface. There are various groups of core data in the Open API, which we will discuss in more detail below. Documentation In order to be able to map the individual components of the API clearly, external documents are usually also made available to explain the API functions, parameters, endpoints or details of the website such as terms of use etc. In the area Docs corresponding references to these documents and schemata can be inserted. The following example shows the format to be used: externalDocs: description: Learn more about user operations provided by this API. url: http://api.api-portal.io/docs/user-operations/ A short description of the document contents is inserted after the parameter description:. The url: parameter also provides the link to the document resource. Details Within the section Details all basic information about the API is provided. This information is also valid API-wide. This section contains important parameters that should be entered. The following source code excerpt describes the individual values in the required format: info: title: Sample API description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML. version: 0.1.9 servers: - url: http://api.api-portal.io/v1 description: Optional server description, e.g. Main (production) server - url: http://staging.api-portal.io/v2 description: Optional server description, e.g. Internal staging server for testing The first section info: describes the function of the API in short words. The parameter title: names a freely selectable title for the API, the second parameter description: names the core function of this API and may also contain external links to a reference source. The version: section speaks for itself and maps the currently used API version. This information is especially valuable for different revisions of an API. The servers: section now lists the active host of this API. In the url: parameter, each base path used is listed individually and in detail. With the parameter description: follows a short description of the path. Security The Security section describes all authentication methods used and permitted in the API. For each entry, there are various parameters that refer to the use of the schema. The following source code excerpt shows an example of the correct use: components: securitySchemes: BasicAuth: type: http scheme: basic BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key OpenID: type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access admin: Grants access to admin operations In addition to Basic and Bearer-Auth, other schemas can also be specified. With OAuth2, several details are assigned to the URLs and scopes. The access level can then be specifically named here. As soon as the security rule is entered in the root, it is valid for the entire API. Here is a possible scenario in which the security schema OAuth2 only allows read and write access: security: - ApiKeyAuth: [] - OAuth2: - read - write Furthermore, a distinction is also made between the possible authentication methods with regard to the individual resource operations such as reading and writing. In the following example, the OAuth2 method with admin rights is defined specifically for read access to invoice information: paths: /billing_info: get: summary: Gets the account billing info security: - OAuth2: [admin] # Use OAuth with a different scope responses: '200': description: OK Resources Typically, an API uses a wide variety of resources such as files, forms, or other information. To access this data, the HTTP protocol also defines various request and access methods. This signals to a browser, for example, how to deal with the request. Basically there are 4 standard request methods which can be applied to resources. In the following we present these together with a simple example parameterization: GET - With this HTTP method a resource can be read. Please note that a GET method must not change any inventory data on the server. To find and read a specific entry using the identifier, use the following query method: GET /user/{userID} POST - The POST method is usually used to create a new resource whose URI is not yet known to the system. This is the default method for adding a new resource: POST /user 2. PUT - Use this method to edit or change an existing and known resource. This method is mainly used for updating data: PUT /user 2 DELETE - To delete a known and existing resource, use the DELETE method with the identifier. Please note the resource rights, if the method call with the user rights can be executed at all: DELETE /user/{userID} The corresponding method parameters are specified in detail for each individual resource. The following source code shows an example of the search for a user data record. Status code 200 for the successful query and codes 400 and 404 for error messages are defined as return values: paths: /user/{userId}: get: summary: Returns a user by ID. parameters: - name: userId in: path required: true description: The ID of the user to return. schema: type: integer format: int64 minimum: 1 responses: '200': description: A user object. content: application/json: schema: type: object properties: id: type: integer format: int64 example: 4 name: type: string example: Jessica Smith '400': description: The specified user ID is invalid (not a number). '404': description: A user with the specified ID was not found. default: description: Unexpected error Types In the type definitions of the API all used business objects are described in detail with ID and the properties together with value ranges. Descriptive categories are also used to better classify the object. In the following example, you create a reusable object in the component container with all relevant properties, data types and scopes: components: schemas: Category: type: object properties: id: type: integer format: int64 name: type: string Errors One or more status messages should also be defined for each API request. This applies in particular to errors that occur. The more precisely you assign error codes to each API call, the easier it will be to handle the interface. Under the parameter responses you define all error codes that can be returned. Use the parameter description: to document the type of error message as a reference to the source. Advantages and disadvantages of Open API With the new version 3 of the Open API many bugs have been fixed and long overdue new features have been added. The large community and the broad application by the Swagger tools will inspire a fast standardization. The participation of many big players and the lack of a vendor lock will also provide a powerful boost. Many well-known frameworks now also rely on broad Open API support. Above all, the broad restructuring in user administration and in the header area makes handling much easier. A further clear advantage are the now reusable objects via their own section. But where there is light, there is usually also shade to be found. Currently, only a few tools and development environments are specifically designed for Open API. Also the reuse of code snippets is not yet available and there are certain incompatibilities between the versions. However, these shortcomings will certainly be eliminated in the foreseeable future. Conclusion The markup language Open API has many advantages and therefore similarities with RAML. However, due to the relatively good selection of code generators and the many tools in the ecosystem, many project managers will prefer Open API. If you attach great importance to extensive language support, this is the right place for you. In the medium term, Open API will probably become the new standard in API documentation, which the already large community will certainly welcome.

One of the biggest benefits of our highly connected digital world is the almost inexhaustible variety of information, knowledge and practical applications. For the latter, it is particularly true that a modern application can access, display and edit the corresponding resources via one or more interfaces. For this reason, these APIs are also subject to special requirements during project planning and development. Such an interface should be described as comprehensively as possible for all participants. This high level of transparency also helps in finding design and program errors. Already in 2010 the eager programmer Tony Tam of Wordnik had big problems that for a structured description of a REST-API interface to be programmed by him the pure enumeration of the used URLs would not be sufficient. The necessary combination of different programming languages and technologies such as WSDL or WADL was also particularly difficult at this time. He found the solution in the definition of his own Interface Definition Language (IDL) for REST-API’s and called this Swagger, which is still available as Open Source under the Apache license. In 2015, the Swagger definition was renamed to the Open API Specification (OAS) as part of the newly established Open API Initiative (OAI). API core elements in Swagger The basis of an API description language always consists of the representation of the individual core elements such as the documentation, the access and end points as well as a detailed description of the used and possible error codes. The more detailed these core elements are described, the easier it is to use and maintain the API. Another important point is the security and thus also the security elements used in the interface. Decisive for the scope of functions are the business objects agreed in the API in the form of type declarations together with all parameters and return values ​​used. The more precisely these specifications are described in the interface, the more transparent and simpler their application, maintenance and integration will be. For the description of these core elements we use as an example a fictitious user store, where a user can register and use the shop for his pet. Docs An important core element for the API is the Docs area. All text resources and documents relevant for the interface can be stored here as references. This can be a function description of the API, a developer documentation or a user manual for the users. For the description of a resource the two parameters description and url are available. The following short code snippet shows a possible application: externalDocs: description: "Find out more about Swagger" url: "http://www.api-portal.io" Details The Details area contains all the important information about the entire interface. This basic information is therefore valid for the entire API. For the corresponding information, some parameters such as description, version, title or host are available. The most important parameters here are basePath and schemes. With basePath a versioning can be entered easily and clearly, by specifying the current directory here. Schemes lists the transfer protocols used for this API. The following source text section shows a possible parameterization: info: description: "This is a sample server Userstore server." version: "1.0.0" title: "Swagger Users" host: "users.api-portal.io" basePath: "/v2" schemes: - "http" Note here the possibilities with the parameters basePath and version. Despite a version 1.0.0 in the parameter version, the base directory in the parameter basePath may be different. Security In an API interface also different authentication methods can be used. This makes it easy to share OAuth 2.0, Digest, and Pass-Through. Each authentication type has a set of required parameters such as type, name, scopes or flow. In the following example, we use OAuth 2.0 for authentication and describe its application in various parameters as follows: securityDefinitions: userstore_auth: type: "oauth2" authorizationUrl: "http://users.api-portal.io/oauth/auth" flow: "implicit" scopes: write:users: "modify users in your account" read:users: "read your users" api_key: type: "apiKey" name: "api_key" in: "header" In the parameter type we enter OAuth2 as authentication method and set the scope to the corresponding write and read methods. Via api_key we define the access key by name and its occurrence in header. Resources To access the host’s various resources through the HTTP protocol, the API first declares the most common access methods. These include the 4 standard method calls GET, POST, PUT and DELETE. Hereby the desired processing is signaled to the respective browser and how the attached parameters are to be used. Below you will find the four method calls with a brief explanation. GET - Read access to a defined resource via the GET method. In our fictitious example of the user shop, a specific animal or product can be searched for and displayed afterwards. The sample call for this is simplified: GET /user/{userId} POST - The POST method is used whenever a new but not existing resource is to be created. In our example we can easily insert a new pet with the following call: POST /user 2 PUT - Use this method to make a change to a resource already in the system. For our example, a change could be simplified as follows: PUT /user 2 DELETE - If a resource in inventory is no longer needed, it can be easily removed using the following method call. The identification is done here via the ID number as follows: DELETE /user/{userId} The interaction of the methods and parameters is briefly described in the following code fragment. We assume that a registered user wants to search the stock for a previously defined pet. For this the userId is used. /user/{userId}: get: tags: - "user" summary: "Find user by ID" description: "Returns a single user" operationId: "getUserById" produces: - "application/xml" - "application/json" parameters: - name: "userId" in: "path" description: "ID of user to return" required: true type: "integer" format: "int64" responses: 200: description: "successful operation" schema: $ref: "#/definitions/User" 400: description: "Invalid ID supplied" 404: description: "User not found" security: - api_key: [] After the method call, the response code is also evaluated accordingly and shows via the 3 evaluation codes implemented here whether the query was successful or if the ID number could not be evaluated. The result can then be displayed formatted to the user. Types In the area of ​​types, all used articles: 205 [business objects] of the interface are now entered and managed. These objects can then be used again and again in different places within the API. The description of an object is carried out by its properties. To stay with our fictitious example of the user shop, you will find in the following source text the description of the user business object User with all parameter definitions: definitions: User: type: "object" properties: id: type: "integer" format: "int64" username: type: "string" firstName: type: "string" lastName: type: "string" email: type: "string" password: type: "string" phone: type: "string" userStatus: type: "integer" format: "int32" description: "User Status" xml: name: "User" An object property such as id is described in this source code using the type: and format: properties. The ID is thus an integer value in the format Int-64. All other properties are similarly defined until the object is fully described. Errors One of the most important definitions of an interface are the possible error or response codes. Using this, the API can make an evaluation of a method call and, in the event of errors, generate a plain text message for the user based on the error code. The declaration always follows the scheme {error code: description / message}. The following example shows the exact notation: responses: 200: description: "successful operation" 400: description: "Invalid ID supplied" 404: description: "Order not found" Pros and Cons of Swagger API development with Swagger offers some significant benefits. On the one hand, there are the widely used project approaches such as Code-First or Contract-/API-First. On the other hand, Swagger offers a language-neutral and above all machine-readable format. The definitions can be encoded in either JSON or YAML. In addition, Swagger also has a relatively simple extension approach. The development is supported by established tools such as the core library (swagger core), the Swagger UI for testing and visualization, the powerful Swagger editor and the code generator (Swagger codegen). Another plus is the huge community and the many code snippets for almost all use cases. However, Swagger can not flexibly reuse code snippets compared to its competitors. Therefore includes or extensions are not reusable, which means significant additional expenses and thus a disadvantage in the programming of the API. In some aspects, such as server specifications or security, Swagger can no longer keep up with the new OpenAPI specification 3. Content negotiation and the expansion of the JSON schema are further plus points for the more modern API description language. Conclusion Especially in the area of ​​the RESTful APIs and the two widely used project approaches Code-First and Contract- / API-First, Swagger is a very good choice. The large community and the numerous tools available for almost all programming languages ​​provide an extremely broad and professional basis for the development of interfaces. The transformation from Swagger to the OpenAPI initiative in the current version 3.0, however, brings many new features and advantages. Several hosts and a much clearer structure support the revised version. With the new OpenAPI specification in the current version 3.0 and the broad support of the well-known manufacturers in the new initiative, however, OpenAPI 3.0 will prevail in the near future and gradually replace Swagger 2.0. Also in the area of tools and code generators, there is still some catching up to do for the OAS, which is ultimately only a matter of time.

The steadily increasing share of web applications is based on the increasing networking between customers and companies. The interaction of the participants is regulated by APIs, which digitally connect the apps and the IT infrastructure. For this reason, it is particularly important that an API is kept as flexible and transparent as possible for its users. Even design errors in the project planning phase can be found and corrected quickly and safely with a well-structured documentation. Especially projects with an API first approach are often subject to a change process, which makes a complete representation of the interfaces and parameters indispensable. RAML (RESTful API Modeling Language) is a descriptive language designed specifically for API First and RESTful API modeling. The goal here is above all the complete provision of all information for the description and generation of an API. Defined by MuleSoft as a specification in 2013, RAML is today in the current version 1 with the release date 2017-07-06. The notation of the API is done in YAML 1.2 format. As language support Java, Node.js, Mule, Phyton and IOT are offered. In addition to the founder MuleSoft, the RAML specification is also supported by Cisco, VMWare, .Net, PayPal, SOA Software, Kin Lane and AngularJS. API core elements in RAML The most detailed and complete documentation of an API is particularly important in terms of usability and maintenance. In terms of content, all important parameters, business objects, error codes and additional information must be described exactly and ideally also with short examples. The core elements shown below should therefore be present in every API description and presented as detailed as possible. We describe the different areas with a fictional example of an airline in which different actions such as bookings, cancellations or requests for information are to be made. Docs For the most detailed description of the API components, corresponding documents can be named in the section docs. A user manual can also be integrated here in the form of links and includes. For this, the two parameters documentation: and title: are available to describe a reference link. It is also a multiple naming of links and descriptions possible. The following source text snippet shows an example: documentation: - title: Home content: | Welcome to the airline Fly Away. We are an european low cost airline. You can find the cheapest airline fares within Europe. - title: Languages content: | Please select a language of your choice for our airline API. We offer the following languages: English, German, Spanish, French and Italian. See our library [languages libraries](http://www.google.com). Details Basic information about the full API is noted in the Details section. For this purpose, various parameters such as info:, title: or servers: are available. In the following source text excerpt you can see an example of our fictitious airline: title: Airline Fly Away API version: v1 baseUri: http://api.dataliquid.com/airline/{version} description: This API allows to interact with our airline Fly Away API. mediaType: application/json The title: parameter should describe the basic functionality of the API. The version specification in the version: parameter is of interest to revision control. The baseUri: parameter specifies the path to the API, which may include a versioning level. In description: you give more information about the API. Under mediaType: you list the format language used for the API. Security In this section, all safety information is noted. Usually the authentication methods used in the API are listed here. The security level and other parameters are defined via various specifications. The following source text section describes the authentication settings for our fictitious company: securedBy: [oauth_2_0] securitySchemes: oauth_2_0: type: OAuth 2.0 displayName: OAuth 2.0 description: | This API supports OAuth 2.0. The necessary ClientId and ClientSecret will be supplied by the provider of the API. Access-Tokens will be issued by means of Id and Secret and are subjected to TimeToLive, short TTL, that is provided when the token is issued. Expired Tokens are rejected by the API with the HTTP Status 403. describedBy: headers: Authorization: type: string displayName: Authorization description: | Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter. example: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3 queryParameters: access_token: type: string displayName: Access Token description: | Used to send a valid OAuth 2 access token. Do not use with the "Authorization" header. example: MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3 responses: The first parameter securedBy: defines the authentication method to be used, which is valid as root over the whole API. This is followed by one or more definitions with a set of parameters such as type:, displayName:, describedBy: and queryParameter:. With these details the used authorization procedure is described in detail. This is followed by information on the access token access_token: and the possible response codes responses:. Resources To define the access to the different resources via the API, different access methods are used in the HTTP protocol. As a rule, the four most common method calls come into question here. These signal to the browser how to handle a request and how to use the parameters it carries. The following list briefly introduces the four method calls: GET - The GET method can be used, for example, to read a resource without changing the inventory data. For our fictitious airline, this call would correspond to a query about a particular flight. POST - The POST method is intended to create a new resource. The resource to be generated must not yet exist in the system. In our example, this method call corresponds to the creation of a new customer booking for a flight. PUT - You can use this method to change or complement a resource that already exists in the system. A change to the flight data, such as the departure time, in an existing booking would be a corresponding example. DELETE - If a resource is no longer needed in the system, you can use this method call to delete it. This would be the case if a customer wants to delete a booking record that has already been saved. In the API, the corresponding parameters are listed in detail for each method call. Using our airline as an example, a visitor searches our website for suitable flights using the search parameters (queryParameters). In the following source text you will find an excerpt of the exemplary definition of the GET method: /flights: get: displayName: Search flights description: Customer searches for flights by using different filters. queryParameters: departure_airport: type: string displayName: Departure airport description: Departure airport according to the IATA airport code. It’s a threeletter code designating many airports around the world. example: "BER" required: false destination_airport: type: string displayName: Destination airport description: Destination airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "LON" required: false flight_type: type: string displayName: Flight type description: Flight is either one way or return. example: "One way" required: false outgoing_flight_date: type: date-only displayName: Outgoing flight date description: The date of the outbound flight. example: "2018-12-11" required: false return_flight_date: type: date-only displayName: Return flight date description: The date of the return flight. example: "2018-12-18" required: false passengers: type: number displayName: Passengers description: Number of flight passengers. example: 1 required: false responses: Types An essential part of the API definition is the detailed representation of the business objects used with all required parameters. Here we also find the object properties like departure_airport:, destination_airport: or price: One of these object types for the flight search (FlightSearchType) we will briefly introduce in the following source code excerpt: types: FlightSearchType: type: object displayName: Flight search type description: User searches for flights and receives information about available flights, date and time, flight number. properties: departure_airport: type: string displayName: Departure airport description: Departure airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "BER" destination_airport: type: string displayName: Destination airport description: Destination airport according to the IATA airport code. It’s a three-letter code designating many airports around the world. example: "LON" price: type: PriceType displayName: Price description: Price of the flight. example: price: 79.99 currency: "EUR" Errors Another important section in the API definition are the communication status messages. These should be listed in as much detail as possible in order to be able to carry out a possible troubleshooting or user message effectively. An error message is returned in JSON format, as the following source code excerpt shows: responses: 404: body: application/json: type: ErrorType example: | { "reason": "RESOURCE_NOT_FOUND", "message": "Resource not found", "trace_id": "550e8400-e29b-11d4-a716-446655440000" } Advantages and disadvantages of RAML Compared to other markup languages such as Open API, RAML offers a simple and convenient way to integrate recurring source code and schemas. There is also an active community that provides excellent support and code snippets. With professional tools like the Atom Plugin API Workbench or the Mule Studio a fast and comfortable project planning is possible. A disadvantage here are the few available tutorials that could make it easier for a newcomer to get started. Another problem is the lack of downward compatibility of the different versions as well as the relatively small number of languages compared to other description languages. Conclusion If you basically need fast and clean designs for RESTful API’s, the RAML description language is currently a clear advantage. Especially with regard to agile API-First projects, the documentation should be kept as simple but transparent as possible. Due to the flexible reusability of objects and code fragments, RAML can clearly score against the competition. With RAML, the integration of XML schemata is completed in seconds. In particular, the API Workbench is very easy and intuitive to use. Nevertheless, it should be noted that due to new developments and advancing standards, the Open API markup language is gaining considerable popularity and will probably be defined as a new standard in the foreseeable future.

The high level of networking of mobile apps, cloud applications and Software as a Service (SaaS) used in business, industry and the private sector places high demands on services and software systems. Complex and powerful API interfaces from the API Economy are now used to implement business requirements. The central key of the offered services are the versatile functions and information that can be used by the open interfaces. Many of the daily used applications are based on different interconnected services. If one of the interfaces involved fails, the service offered no longer works! To ensure that the functionality, reliability, performance and security of the APIs are met, API testing is a must. For API tests, the APIs (Application Programming Interfaces) are tested directly and within the framework of integration tests. The tests are performed at message level. The incoming data as well as the expected results of the interfaces are tested. The regular and automated execution of the tests during the API lifecycle ensures that the APIs are error-free and stable. Quality assurance is an important component in the provision of highly available APIs.

Powerful APIs are characterized by a wide range of functions. In addition to the functions, the technical data is the most important factor for acceptance by API consumers. Business objects define the technical data structures which can be exchanged between the respective API function and the consumer. API resources (function of an API) distinguish between business objects for the request and for the response. All business objects used in an API are described and managed in the API Definition. The business objects can be reused within an API. As an example, we will take an Order API, with which new orders can be created and the order status can be retrieved. If an order is created via the API, the data structure of the order type must be transferred to the API. The data fields and data types are defined in the data structure. The data type specifies the type of the data field, for example, numbers, character strings, or lists. An OrderType consists of the following information: Order number Customer number Order date Order items Order status The common API specifications support almost all data types. The following simple data types are the most commonly used: string number (decimal number) integer boolean (truth values true, false) array (list of values) date The data types are now defined for the data fields mentioned above in our example. An order number can consist of characters and numbers, so we define string. The customer number consists only of numbers and is therefore number. The order date is declared as date-only according to the international date and time format ISO 8601. The order items are an array, since several items can be contained in an order, which are defined as independent business objects. In addition, further facets of a data field can be declared. The more comprehensively an API is defined, the more stable and resilient an API is. The minimum and maximum length of a data field of type string can be defined by facets. For example, the field may contain a minimum of 2 characters and a maximum of 20 characters. If the data field Price of type number is described, the minimum value and maximum value as well as the decimal places can be defined. As an example, the price must be at least 0.00 and at most 5,000 of a currency unit. Two decimal places are allowed. The example values NEW, SHIPPED, DELIVERED and CANCELED can be specified for the order status data field, making it much easier for the user to understand the data field and its use. For each data field a technical example value can be given, this creates a substantial increase in value for the user, since the understanding and usability of the API is practically clarified. By a strong characteristic of the business objects the API achieves a high transparency. This makes it easy for interested parties and developers to understand and use the interfaces and the underlying business processes.