A plug is basically a device that serves as a bridge for energy(electricity, heat, etc.), be transferred from one place or device to another. That said, an API serves the same function as a plug in the software development arena.
The term API, short for Application Programming Interface, is part of a computer program designed to be used by another program instead of that designed to be used by a human. APIs are mostly used to refer to a specific kind of API, the web API, instead of APIs in general. A web API allows for information to be operated on by other programs via the internet. For example, Facebook, Twilio, or Twitter’s API.
Computer programs (applications) regularly need to communicate amongst themselves or with the operating system, and APIs are one way to do it.
Please note that the term APIs refers to web APIs in this article.
Table of contents
Introducing
Using APIs
API Design Principles
API resources.
Introduction
APIs are tools for making information and application functionality accessible over the internet. The focus of this lesson is: Learning what an API is and when you should use one. Learn some principles of good API design.
When to Create an API: consider an API if:
Your users will need to access your data in real-time. Your data is updated frequently. Your users only need access to a part of the data at a time. Your data set is large, which makes downloading resource-intensive. Depending on the resources at your disposal, creating an API will be dependent on the size of the data. If the data you want to make available is relatively small, it will be more efficient to provide it in the form of a downloadable file rather than creating an API for it.
API terminology:
HTTP (Hypertext Transfer Protocol) is the primary means of passing/communicating data on the web. HTTP implements several “processes” which tell which direction data is moving and what should happen to it. Some of the most common are POST (which pushes new data to a server), GET (which pulls data from a server), and UPDATE ( which modifies existing data which a new data) URL (Uniform Resource Locator) is the web address/ address for a resource on the web, such as hashnode.com/about. A URL describes the location of a specific resource, such as a web page. A URL is made up of a protocol (HTTPS://) , domain (hashnode.com) and path(/about).The terms request, URI, or endpoint are used to describe related ideas when learning about APIs. This article will prefer URL (GET request) to avoid complications. REST (Representational State Transfer) is a style guide that depicts some best practices for implementing APIs. REST APIs refer to APIs designed with some or all of the REST principles in mind. JSON (JavaScript Object Notation) is a text-based storage format designed to be easy to read for both humans and machines. It is the most common format returning data through an API. What Users want in an API: URLs make access to information or resources through an API easier, faster, and more intuitive. Documentation serves as the start point (guide) to working with a new API. An excellent developed API has good documentation and well-planned URLs.
API Design Principles
Before building a more functional API application, let’s look at some of the API design decisions. One of the two main signs of a good API is usability and maintainability. So as you keep on designing, developing, and implementing more functionality into your API, keep the following considerations in mind: Designing Requests: The most common and standard design of modern APIs is called REST. The basic concept about REST is that it is based on four methods defined by the HTTP protocol: POST, GET, PUT, and DELETE, which is similar to the traditional actions performed on data in a database: CREATE, READ, UPDATE and DELETE. This article will only be discussing GET requests, which are equivalent to reading from a database. Because of the integral role that HTTP requests play in using a REST API, many of the design principles revolve around how requests should be formatted. To understand the process that goes into formatting an HTTP request, let’s first consider a poorly-designed example of an API endpoint: api.com/getdiarie/5 The main actions done by a REST API are GET, POST, PUT or DELETE, which are determined by the request method rather than in the request URL. The formatting of our example API request above has several issues, such as semantic. This means the word ‘GET’ should not appear in our request since ‘GET’ is implied by the fact that we’re using an HTTP GET method. The use of plural nouns to denote resource collections/records makes it easier when referring an API to a collection/record(emails, books, addresses) or an entry(address, book).
Making use of this principle in our API will be this:
http://api.com/getdiaries/5
The request uses part of the path to provide the ID (/5). While this is a strict and uncommon approach, URLs created in this manner can only be filtered one field at a time. Query parameters allow for filtering by multiple database fields and make more sense to provide “optional” data, such as an output format: api.com/getdiaries/?author=John+Doe&pub.. Planning for future additions when designing how your API requests should be structured makes more sense, even if the current version serves only one type of resource (addresses, books, diaries, etc.). example, planning to either add resources or non-resource functionality to your API in the future:
http://api.com/resources/getdiaries?=5
Adding a different category/segment to your path, such as “resources” or “entries,” gives you the capability to allow users to search across all resources available, which makes it easier to support requests later. Another plan for the future is to add a version number to the path. This simply gives you the option to continue to support your old API while releasing a second version with improved or different functionalities. This approach makes your applications independent since scripts and apps built using your old version of your work won’t stop working after your upgrade. An example of an API built with this philosophies will be like this: api.com/v1/resources/getdiaries?id=10
Documentation and examples
Documentation plays a crucial role in the usability of every application. All APIs should have documentation describing the functionality or resources available through your API that also showcases working examples of request URLs or code for your API. You should document each section for each resource that describes which fields, such as ‘id’ or ‘name’, it accepts. Each section should be linked with an example in a sample HTTP request or block of code. A common practice in documenting APIs is to provide annotations that are automatically collated into documentation using a tool such as [Doxygen ]doxygen.nl) or Sphinx . These tools create documentation from docstrings (comments made in function declarations). APIs documented to this level are not good enough but should be documented with a potential user in mind and add some working examples.
In an ideal world, an API would have 3 different types of documentation:
- A reference that explains each route and its behavior 2. A guide that explains the reference in prose 3. One or two tutorials that explain every step in detail.
For inspirations on API documentation, see:
- New York Public Library Digital Collections API
- MediaWiki Action API
World Bank API
New York Times API
Europeana Pro API