DEV Community

Cover image for API: Def, Types, Spec, and Docs. A stone's throw into the application programming interface
Dule Martins
Dule Martins

Posted on

API: Def, Types, Spec, and Docs. A stone's throw into the application programming interface

You don't have to be around the tech space for months before coming across the word API. Words like API shouldn't be a new thing to anyone that reads tech magazines or blog posts like what you are doing now, one thing reading of blog post and a tech magazine helps you with is getting familiar with buzzwords in the tech space.

Before learning web development the word API sounded like a complex term that would be difficult to understand and start running with. Over time the term has become a frequently used word, companies are now developing API as a product and creating a role for documentarians to help them organize and structure words that will enable their users to use their API without any difficulty.

I got to know about the history of API after reading about it on RED HAT.

APIs emerged in the early days of computing, well before the personal computer. At the time, an API was typically used as a library for operating systems. The API was almost always local to the systems on which it operated, although it sometimes passed messages between mainframes. After nearly 30 years, APIs broke out of their local environments. By the early 2000s, they were becoming an important technology for the remote integration of data.

Technically, API stands for Application Programming Interface. Most large companies have built APIs for their customers, or for internal use, or as a Product, as a means of collaboration between two different and remote companies.

The Web as an Instance

Think about the Web as a large network of connected servers, where we make a request through HTTP and get a response that is been define in a structured way.

The web provides information to users from a remote server, every web page on the internet is stored somewhere on a remote server that receives request and process response.

When you type a web address into your browser, a request goes out to the web remote server. Once your browser receives the response, it interprets the code and displays the page.

API Def.

While the acronym is commonly referenced, few understand its actual meaning. Like we clearly stated above what the acronym represents. Understand that software is built to communicate, this is the whole essence to while most software applications are built with the integration of APIs that serve then data from other applications, it could be to communicate with a store by placing orders and check out or a bank by processing payment or transfer.

Software or its elements don’t need a graphical user interface to communicate with each other. Software products exchange data and functionalities via a machine-readable medium which can be likened to – Application programming interfaces.

An API is a set of programming code that enables data transmission between one software product and another. It also contains the terms of this data exchange.

Types of API

There are severe types of APIs and some APIs are been made available base on their release policy. API release policy could be Private, Partner, and Public. For example, with Javascript API you can perform an action like While the browser usually is 'above' any code running in it, a Mozilla-derived API allows JavaScript limited access to browser settings. Think about aspects such as reading the user's homepage, how bookmarks are handled, and where new tabs show up.

API release policy:

  • Private: These APIs are solely used within an organization and In-house developers use these APIs to integrate a company’s IT systems or applications, build new systems or customer-facing apps leveraging existing systems. The private strategy allows a company to fully control API usage.

  • Partner: Openly promoted but available for known business partners who have signed an agreement with the publisher or the API company. The common use case for partner APIs is software integration between two parties. For example, an e-commerce platform like Timiun integrated a payment API develop and publish by Monify

  • Public: These types of APIs are publicly available to use like OAuth APIs from Google. It has also not given any restriction to use them. So, they are also known as Public APIs.

APIs can be classified according to the systems for which they are designed. There are Database APIs that enable communication between an application and a database management system. working with databases by writing queries to access data, change tables, etc.

Web APIs provide machine-readable data and functionality transfer between web-based systems which represent client-server architecture. These APIs mainly deliver requests from web applications and responses from servers using Hypertext Transfer Protocol (HTTP).

API Spec

An API spec is made up of a plan of how your API should look structurally - like an architectural design of a product. The best part of an API Spec is that it enables you to isolate design flaws or problems before you write a line of code.

The advantage that comes with planning your API specification is something worth the time put in. Building your API base on specification could possibly add two or more weeks to the deadline for the development life-cycle, but it worth it.

The idea behind APIs is simple, it should be flexible enough to be used by anyone and adequately documented to enter face with the developers using it. Most time thinks of API having customer support where a developer could chat up the support about the difficulties s/he could be facing integrating using the API, but this is while we have Technical writers and Documentarians I supposed.

API Docs

API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API -

As stated above, API documentation is a company's customer support system for marketing their API, so you understand how effective and the amount of effort that has been put out to have that ready for consumption.

Is easy to ready documentation but it is more fun when it is properly structured in a manner that a user can easily locate what s/he is looking out for. Most documentation teams while building the docs for their APIs are responsible for continuous maintenance of the documentation, so they basically design means of getting feedback from users on how to improve the docs.

Once I heard someone saying "if you don't document it then it didn't happen", documentation is an art of credibility, and reading documentation carefully is an art of consistency.

Thanks for reading !!!!

Top comments (0)