All You Need to Know About APIs

What Is an API?

An application program interface (API) is a set of routines, protocols, and tools for building software applications. Basically, an API specifies how software components should interact thereby exposing business capabilities and services.

Characteristics of an API
  • APIs enable organizations to share information with external developers, business associates, and other teams within the same organization.
  • APIs allow you to expose some functions of a program or service in a managed and secure environment.
  • A high-quality API facilitates the development of applications by allowing different functionalities to be created independently while offering a complete set of capabilities for development.
Why API?

APIs are needed for the following reasons

  • Supporting easier access to customers and partners.
  • Extending the reach to more channels and devices.
  • Surfacing of services for more flexibility.
Classification of APIs
  • External (public): APIs are open to any developer who wants to sign up. Apps are more targeted towards end consumers.
  • Partner (protected): APIs are open to selected business partners. Apps are more targeted towards end consumers or business users.
  • Internal (private): APIs are exposed only to existing developers within the enterprise. Apps are more targeted towards the employees of the enterprise.
API Lifecycle

The API lifecycle consists of four main components related to API management, which includes creating, running, managing, and securing APIs.

  • Creating APIs: Creating APIs involves developing and writing the API definition and implementation, identifying and debugging defects, and submitting the code and application through testing to ensure the functionalities work as required
  • Running APIs: Running APIs involves staging, packaging, and publishing the API.
  • Managing APIs: API management include the set of rules and conditions that govern the API; where, how, and with whom the API is shared; and if the API is meeting its stated purpose.
  • Monitoring APIs: Access control, monitoring, and logging are necessary functions of properly securing an API.
What makes an effective API design

APIs are excellent platforms for collaboration and innovation. APIs are the foundation for many web and mobile applications.

  • Ease of Use: APIs with a good design are easy to learn and work with so that new users are able to quickly understand the operating governance structure.
  • Version Support and Documentation: High quality APIs have extensive and accessible documentation to aid developers as they work with the API. Examples of tools for api documentation swagger and apidocs 

Representational State Transfer (REST) API is an architecture style for building resources on the web. Examples of resources for website include HTML documents, images, and script files.


To retrieve or update a resource, perform an action through HTTP methods, and to identify which resource to retrieve or update, REST uses a Uniform Resource Identifier (URI) to describe the network location of the resource.

HTTP methods

REST provides the following HTTP methods and for this article I will be using images from an POSTMAN (API Development Environment):

  • GET

The GET method is used to retrieve information from the server.

What simply happens here is an user makes a get request to an URI ( and then parses a parameter of 1 to request for the first post.

Get Request

NOTE: Each parameter is represented as a name-value pair (NAME = post , VALUE = 1)

  • POST

The POST method is used to post data to the server. In this case, the parameters are posted in the body of the request, not in the URI.


The DELETE method is used to delete a resource from the server.

delete api

  • PUT

The PUT method is used to update a resource from the server.

update resource

  • HEAD
  • LINK
  • LOCK
What is JSON?

JavaScript Object Notation (JSON) is a text format for structured data. Its syntax is derived from the object literals of JavaScript, according to the ECMA-262 ECMAScript language standard, third edition, which is the scripting language standard.

JSON Characteristics
  • JSON is a platform-neutral and language-neutral data format.
  • The main design goal of JSON is to provide a minimal, portable, textual data interchange format.
  • JSON is not a markup language. Unlike XML, it does not use descriptive tags to encapsulate its data.
JSON Data Types

JSON features the following data types:

  • String is a sequence of zero or more Unicode characters. For example: “Hello world!\n”.
  • Number includes an integer (0-9) or a fraction (0.5) or an exponent (-1.4719e7).
  • Object: An unordered collection of zero or more name-value pairs. Denoted by curly brackets. Example {“name” :”Larry”, “age” : 22, “vegetarian” : false}
  • Array: An ordered sequence of zero or more values. Example:


You should now have a better understanding of APIs, API lifecycle, REST, JSON, and how to consume REST.

Special thanks to IBM DIGITAL NATION AFRICA for putting up resources to enable craft and document my learning experience, gained new knowledge along while learning and I hope you will too. My badge of course completion is here.


Related Posts