Application Programming Interface

Discussion

• Why do we need APIs?

  APIs connect different applications. It can connect two or more components from separate applications to perform some functions and share data. APIs are useful for building strong and robust applications since they allow developers to reuse capabilities while also reducing code size, which enhances user experience and application security.

  Many businesses use API to provide a smooth experience of using backend architecture, allowing users to interact with them more easily. It's often shared with third-party developers so that they can integrate it with other services. It also reduces the issues of incompatibility and eliminates the need for recreating it for various platforms conversions which is expensive.

  APIs provide flexibility to businesses by allowing them to easily connect with their new partners or provide new services from existing products. They can easily switch to create new products, which could potentially generate large profits.

  Ultimately, APIs are designed for machines, not humans. API is not directly related to UI/UX. In the world of IoT and automation, APIs are becoming critical. Siemens has patented the concept of human programming interfaces for future human-machine interaction in an automation environment.

• What is an API-first approach?

  

  An API-first approach. Source: Fernando 2020.

  The concept of API-first started with the adoption of microservices in which applications are built as independent components and coupled together via API. Major companies such as Netflix, Amazon, and PayPal have moved to microservices architecture for their applications with great success.

  API-first refers to giving APIs first priority in the development of software products. There's no widely accepted definition of the term API-first. This API-first strategy improves developer experience by introducing consistency, as they employ the same format and styles throughout the development. A style guide may be utilised by teams throughout since it documents the status code, error handling techniques, versioning strategies, and other API specifics. It ensures the consistency and reusability of all APIs.

  The OpenAPI Specification is the most extensively used API specification language (also known as the Swagger Specification). While alternative API definition languages, such as RAML and API Blueprint, exist OpenAPI has become the standard practice.

• What are the characteristics of a good API?

  We note three characteristics:

  • Effective Documentation: API documentation is a written reference for effectively utilising API functionalities. It should be simple for developers to grasp. A solid API documentation should be created for users who are unfamiliar with that specific API. It should also include examples describing usage of various functionality in an API created through documentation software.
  • Error Handling: Precise usage of error codes is must in an API. Error codes in responses help clients to understand the exact cause of the problem. Appropriate HTTP status code will also provide a positive user experience. Besides alerting them, these assist clients in fixing the problem. Generally, error codes 400-499 imply client-side errors, while 500-599 imply server-side errors.
  • Authorization and Authentication: Authorization is a process of evaluating access privileges to an endpoint or a method of an API, whereas authentication is the process of validating credentials like user session, id, or password provided through the request.
• What is meant by implementation hiding in API design?

  

  Implementation hiding when dining at a restaurant. Source: Lauret 2019.

  In the restaurant example above, a customer interacts only with the waiter and not the cook. The waiter informs the cook the order, picks up the order when it's ready and serves it to customer. The customer has no idea what happened in the middle or how the meal was prepared by the cook.

  Similarly in software, an ideal API will hide its implementation details. It will provide a generic solution without exposing implementation. This is called information hiding. API users don't care about inner workings. All they expect is simplicity of use. Furthermore, by concealing implementation details the API provider can subsequently alter or improve inner workings without impacting client applications that consume the API. This also builds trust with clients.

  Sometimes an API fails to properly hide underlying implementation details. We call this a leaky abstraction, which is something to be avoided.

• What are the different types of API?

  Categorised by use cases, we note the following:

  • Operating System APIs: These APIs ensure tasks run inside operating systems smoothly. It interacts with its own resources and services. These APIs will be specific to each operating system. Linux employs kernel-user space API, while Microsoft uses Windows API.
  • Remote APIs: Provider and consumer of the API are on different machines. They communicate over a local network and/or the internet. These APIs are typically developed in web standards. Java Database Connectivity API is a remote API in Java. Even though not all remote APIs are web APIs, they can be thought of as remote APIs.
  • Web APIs: These primarily use HTTP to receive requests/responses in the form of XML or JSON. These are often synchronous and stateless.
  • Database APIs: These APIs are used as interface between database management systems and applications in order to query, read, write, or modify data on a remote database. In general, backend APIs are asynchronous and stateful. They facilitate complex integrations.
  • Language APIs: Programming languages provide built-in APIs such as classes, methods, macros and even extensive libraries, such as Collections in Java and Standard Template Library (STL) in C++.
• What are the different types of release policies for an API?

  Here are some API types organised by release policy rather than design style:

  • External or Public API: It's extensively used by third-party developers or users external to the organization. It's built with most robust technologies keeping high consumption in mind. Google Maps API is one example of Public API which is widely used by delivery apps and ride-sharing companies for directions and real-time location tracking.
  • Internal or Private API: It's for internal use typically within a team or organisation. It's a common type of API that is simple to develop as it doesn't require robust infrastructure for small consumer base. Because of recent practices like DevOps and microservice architecture, this type of API is essential.
  • Partner API: This is neither entirely private nor completely public. These APIs can be accessed by people outside the organisation or team but with special authorization. Examples include Twitter or AirBnB, where access is restricted to authorised users only.
  • Composite API: Composite APIs merge many API data requests into one. It saves data usage in applications by reducing the amount of API requests.

Milestones

1960

Developers start building libraries to share procedural language capabilities with other developers. Because API has no formal definition, this is a conceptual application. These languages have subroutines, which are chunks of code that can be invoked and collaborated on by other programmers. It can be used without exposing the internal code of the libraries.

Dec
1968

In the paper titled Data structures and techniques for remote computer graphics, Cotton and Greatorex use the term Application Program Interface (without -ing suffix). This paper describes independent hardware for computer graphics system.

May
1981

In a dissertation, Nelson introduces a new method of API interaction called Remote Procedure Call (RPC). It can communicate with a piece of code on another remote server, just like a local computer.

1988

Portable Operating System Interface (POSIX) standard is introduced to solve the portability issues. It defines an interface between hardware and operating system, specifying application programming interfaces (APIs) at the source level.

1990

Malamud, in his book Analyzing Novell Networks defines API as "a set of services available to a programmer for performing certain tasks."

Oct
1991

Functioning of ORB in a client/server environment. Source: Oracle Docs.

Object Management Group (OMG) defines the Common Object Request Broker Architecture (CORBA) as a standard. In CORBA, software components are treated as objects running on multiple systems and able to communicate with one another. An object could be written in any programming language. Objects are specified using an Interface Definition Language (IDL) syntax. The version 1.0 release supports C Language mapping. CORBA uses Object Request Broker (ORB) to communicate between client and server applications.

Sep
1996

Microsoft introduces Distributed Component Object Model (DCOM), an improved version of the older Component Object Model (COM) for Windows 95. This enables communication between components like as ActiveX controls, scripts, and Java applets that exist on several machines on a LAN, WAN, or on the Internet through the use of Remote Procedure Calls (RPCs), allowing distributed communication across multiple networks.

Nov
1999

Microsoft, UserLand Software and DevelopMentor jointly release Simple Object Access Protocol (SOAP) which uses Extensible Markup Language (XML) syntax to send RPC messages over HTTP. SOAP links COM and DCOM objects and runs natively in Windows 95, 98 and NT. It can also connect with Internet Explorer and Java.

2000

General Model of a REST API with request and response. Source: Documenting APIs.

Roy Thomas Fielding, a Ph.D scholar, introduces the concept of Representational State Transfer (REST) in his dissertation. It's a network-based architectural style that later popularizes the usage of web APIs.

Feb
2000

Salesforce launches its web API at the IDG Demo conference. It's a enterprise-class, web-based Salesforce automation offered as a "Internet as a Service." In December, eBay launches their API to a selected number of developers and partners.

Jul
2002

Amazon Inc launches Amazon.com Web Services API. This enables developers or third-party websites to display Amazon products in their websites in XML format.

Mar
2008

Apple releases iPhone 2.0 software. This includes the iPhone Software Development Kit (SDK). The SDK comprises a set of APIs and tools for developing iPhone and iPod applications. It also includes Core OS, Core Services, Media, and Cocoa Touch interfaces.

Feb
2015

Google open sources gRPC, a framework for handling remote procedure calls. The underlying transport protocol is HTTP 2.0. gRPC differs from HTTP in that it is based on the Remote Procedure Call (RPC) model, in which addressable "entities" of a collection are called procedures and the data is hidden behind the procedures. In contrast, in HTTP, addressable entities are called "data entities" and their behaviour is hidden behind data. Because gRPC is founded on HTTP 2.0 standards, it has many more capabilities that help speed up services while conserving resources such as energy and data.

Sep
2015

When Facebook developers attempt to build native Facebook implementations for iOS and Android instead of using the mobile-webview, which had some restrictions, they start to run into a lot of problems. They tried to use RESTful architecture, but it didn't meet their needs because they wanted the data to look like a graph of objects and models. They needed an API to display the newsfeed, which had previously been displayed as HTML. As a result, they create GraphQL, a new project that defines data query language in a new way to assist product designers.

Jun
2019

According to Programmable Web, an API research website, its API directory surpassed 22,000 APIs. Every month, an average of 220 APIs are introduced, representing a 30% increase over the previous four years. API adoption has been growing since 2005. API developers have begun to offer APIs in alternative architectures such as GraphQL and gRPC in addition to traditional REST, resulting in a larger directory.

References

1. AltexSoft. 2019. "What is API: Definition, Types, Specifications, Documentation." Blog, Altexsoft, June 18. Updated 2021-07-28. Accessed 2022-08-02.
2. Amazon Web Services. 2022. "What is an API? - API Beginner's Guide." Amazon Web Services, Inc. Accessed 2022-06-02.
3. Annenko, Olga. 2022. "What Makes a Good API | 6 Aspects That Make it Fit for Integration in 2022." elastic.io, January 20. Accessed 2022-07-12.
4. Apple. 2008. "Apple Announces iPhone 2.0 Software Beta." Press release, Apple, March 06. Accessed 2022-07-09.
5. Barry, Douglas K. 2022. "Application Program Interfaces (APIs)." Service Architecture, Barry & Associates, Inc. Accessed 2022-06-26.
6. Bhui, Jaidev Singh. 2022. "What exactly is an API - Explained in simple terms." Blog, Crio, February 15. Accessed 2022-08-09.
7. Blobr. 2021. "Why APIs Are the Secret Ingredient for Success With IoT." Blog, Blobr, September 14. Accessed 2022-08-14.
8. Byron, Lee. 2015. "GraphQL: A data query language." Facebook Engineering, September 14. Accessed 2022-07-06.
9. Cotton, Ira W., and Frank S. Greatorex. 1968. "Data structures and techniques for remote computer graphics." AFIPS '68 (Fall, part I): Proceedings of the December 9-11, 1968, fall joint computer conference, part I, ACM Other conferences, December. Accessed 2022-06-18.
10. Fernando, Chanaka. 2020. "How to create new business opportunities with API-First strategy." Blog, Solution Architecture Patterns, on Medium, October 20. Accessed 2022-08-14.
11. Fielding, Roy Thomas. 2000. "Network-based Application Architectures." Chapter 2 in: Architectural Styles and the Design of Network-based Software Architectures, Dissertation, University Of California, Irvine. Accessed 2022-06-24.
12. Harris, Tony. 2021. "3 Reasons Why You Need An API." Blog, DreamFactory Software, October 26. Accessed 2022-07-07.
13. IBM Cloud Education. 2020. "What is an Application Programming Interface (API)." IBM Corporation, August 19. Updated 2021-10-15. Accessed 2022-08-13.
14. IBM Documentation. 2021. "Common Object Request Broker Architecture (CORBA)." IBM Integration Bus, Version 9.0.0.8, IBM, March 01. Accessed 2022-07-01.
15. Janeiro, Jordan and Geir Sjurseth. 2021. "The differences between synchronous web APIs and asynchronous stateful APIs." Blog, Google Cloud, September 14. Accessed 2022-08-15.
16. Jeremy H. 2020. "API-First: The Advantages of an API-First Approach to App Development." Blog, DreamFactory Software, November 13. Accessed 2022-07-10.
17. Jin, Brenda, Saurabh Sahni, and Amir Shevat. 2018. "Designing Web APIs." O'Reilly Media, Inc. Accessed 2022-06-27.
18. Johnson, Tom. 2020. "What is a REST API?" Documenting APIs, March 15. Accessed 2022-08-09.
19. Josey, Andrew. 2020. "POSIX™ 1003.1 Frequently Asked Questions (FAQ Version 1.18)." The Open Group, June 13. Accessed 2022-06-25.
20. Kata, Anji. 2020. "Security Best Practices for REST APIs." Dzone, July 21. Accessed 2022-07-13.
21. Kondov, Alex. 2022. "Leaky Abstractions." May 27. Accessed 2022-07-30.
22. Lane, Kin. 2019. "Intro to APIs: History of APIs." Blog, Postman, October 10. Accessed 2022-06-24.
23. Lauret, Arnaud. 2019. "What is API design?" Chapter 1 in: The Design of Web APIs, Manning Publications. Accessed 2022-07-18.
24. Lokare, Ishwari. 2021. "The Evolution of APIs: From RPC to SOAP and XML (Part 1)." Blog, Kong Inc., November 17. Accessed 2022-06-27.
25. Malamud, Carl. 1990. "Analyzing Novell networks." Van Nostrand Reinhold. Accessed 2022-06-22.
26. Manutan. 2020. "API: Definition and application in procurement." Glossary, Manutan, March 26. Accessed 2022-06-02.
27. Marculescu, Mugur. 2015. "Introducing gRPC, a new open source HTTP/2 RPC Framework." Blog, Google Developers, February 26. Accessed 2022-07-07.
28. Masand, Ankita. 2020. "What is GraphQL and why Facebook felt the need to build it?" Buddy, October 12. Accessed 2022-07-06.
29. Microsoft. 1996. "Microsoft Releases Beta Version of DCOM for Windows 95." Microsoft News, September 18. Accessed 2022-06-20.
30. Microsoft Docs. 2020. "COM, DCOM, and Type Libraries." Win32 Documentation, Microsoft, August 08. Accessed 2022-07-02.
31. Mulesoft. 2022. "What is an API? (Application Programming Interface)." MuleSoft. Accessed 2022-06-03.
32. Mulesoft. 2022a. "Types of API management strategies." mulesoft.com. Accessed 2022-07-20.
33. Nelson, Bruce Jay. 1981. "Remote Procedure Call." Xerox - Palo Alto Research Center, May. Accessed 2022-06-28.
34. Opidi, Alfrick. 2020. "API Documentation Best Practices." Blog, RakutenRapidAPI, February 13. Accessed 2022-06-10.
35. Oracle. 2022. "The CORBA Programming Model." CORBA Technical Articles, Oracle® Tuxedo, 11g Release 1 (11.1.1.3.0), Oracle, December. Accessed 2022-07-05.
36. Reddy, Martin. 2013. "The #1 Rule of API Design." SciTech Connect, Elsevier, November 15. Accessed 2022-07-15.
37. Redhat. 2022. "What is an API?" Redhat, June 2. Accessed 2022-06-03.
38. Sandoval, Kristopher. 2017. "Best Practices for API Error Handling." Nordic APIs, June 15. Accessed 2022-07-13.
39. Santos, Wendell. 2019. "APIs show Faster Growth Rate in 2019 than Previous Years." ProgrammableWeb, July 17. Accessed 2022-07-08.
40. Simpson, J. 2022. "6 Types of APIs: Open, Public, Partner, Private, Composite, Unified." Nordic APIs, March 15. Accessed 2022-07-20.
41. Sintes, Tony. 2001. "Just what is the Java API anyway?" Blog, InfoWorld, July 13. Accessed 2022-08-09.
42. Wagner, Janet. 2021. "API-First vs. API Design-First: A Comprehensive Guide." Blog, stoplight.io, August 09. Accessed 2022-07-25.
43. Wagner, Janet. 2022. "Understanding the API-First Approach to Building Products." Swagger. Accessed 2022-07-10.
44. Walsh, Jeff. 1998. "Microsoft spearheads protocol push." Infoworld, July 10. Accessed 2022-07-04.
45. Wang, Lingyun, and Arquimedes Martinez Canedo. 2017. "Human programming interfaces for machine-human interfaces." US20170108834A1, Patent Application, April 20. Accessed 2022-08-13.

Further Reading

1. Bloch, Joshua. 2006. "How to Design a Good API and Why it Matters." Google Research. Accessed 2022-07-20.
2. RapidAPI Staff. 2021. "How To Use an API (The Complete Guide) [A Simple API Example]" RapidAPI Blog, October 12. Accessed 2022-07-11.
3. Postman. 2019. "Introduction to APIs." Postman Youtube Channel, December 19. Accessed 2022-07-20.
4. Ashby, Dennis, and Claus T Jensen. 2014. "APIs For Dummies." John Wiley & Sons, Inc., December. Accessed 2022-07-11.

Article Stats

Author-wise Stats for Article Edits

Author

No. of Edits

No. of Chats

DevCoins

ajithkumarkdas

8

6

2095

arvindpdmn

4

5

895

DevCoins due to articles, chats, their likes and article hits are included.

Cite As