APIs — General Terms

4 min readMay 26, 2021

In this article, I would like to give some basic information about APIs.

What is API

Today, API is one of the most important term for application development. It’s usage and importance is getting understand by more people day to day. Actually API is acronym of “Application Programming Interface”, it allows two application to talk to each other. It is an interface not for the users but for the programs.

We can use APIs for several purposes, most important of them listed below:

1. In this digitalization era, data is most important element to digitized and smart future. Companies can share the data via the APIs. It can be thought as internal and external.

2. For internal usage (Private API), we can build APIs to communicate between teams/functions. APIs help to build a microservice architecture in the company which contributes to become more agile and for continuous development/integration. The main reason is APIs reduce the dependency between the functions. In API environment, we can change our code with no effect to the other integrated parts if we stick and apply the predetermined contract.

3. For external usage, Open(Public) API term is used. Open API allows to public developers to get data via APIs.

4. Out of the data perspective, APIs can be used for the sharing application functionalities. One may be use a function of an application via API.

5. A business model can be created with using the Open APIs.

API SPECIFICATIONS

API has a contract involves the rules for the integration, a classic analogy of this contract “electric sockets”. For electric sockets, it is determined the shape, voltage etc, you can use every socket with your device designed for that socket. For API, we can simply develop a program to integrate with the API by using its contract. Indeed contract means documentation involves all information about the API. There are some file formats allow you to create a contract, the most common format is OpenAPI Specification.

OpenAPI Specification is an API description format for REST APIs.

While passing the the specifications formats, I would like to digress to give definition and main difference REST and SOAP.

· SOAP: Simple Object Access Protocol is a standards-based web services access protocol. SOAP can work with XLM formats.

· REST: Representational State Transfer is an architectural style for providing standards between computer systems on the web, making it easier for systems to communicate with each other. REST can work with plaint text, HTML, XML, JSON etc.

These specifications can be written in YAML or JSON format. JSON is acronym of “JavaScript Object Notation” and is actually data-interchange format. It is easy for humans to read and write and for machines to parse and generate.

· An object is a collection of key-value pairs, surrounded by curly braces

· The key-value pairs are each put into double quotation marks when both are strings. If the value is an integer or boolean, omit the quotation marks around the value.

· Each key-value pair is separated from the next by a comma.

· An array is a list of items, surrounded by brackets.

YAML is a data serialization language. YAML stands for “YAML Ain’t Markup Language”. When compared others YAML removes brackets, curly braces and commas but uses spaces, colons, and hyphens to indicate the structure.

· Spacing is significant. Each two-space indent represents a new level.

· Each new level is an object.

· Each level can contain either a single key-value pair or a sequence.

· The values for each key can optionally be enclosed in quotation marks.

We have covered the OpenAPI Specification format and its usage. Another way to create a contract is RAML. RAML is acronym of “RESTful API Modeling Language”. RAML and OpenAPI Specification format can be used based on the API project or company constraints.

In this part, creating an API specification in RAML steps are listed below: