API Design

Classification of the Skill

An Application Programming Interface (API) describes the interface that a programmer works with in order to communicate with a library, software development kit (SDK), framework, web service, middleware, or any other piece of software. In general, API allows interaction or communication between two software components. APIs are used to expose an existing system’s functionalities to the other system or software, for that, set of functions or procedure is defined which takes set of parameters as input and generate an output by performing some business logic. APIs are primary ways in which businesses nowadays deliver data to their own frontend and also to other clients that purchases that business’s services. ^[1]

APIs are designed by programmers to be used by a programmers. Usability of API is an important factor while designing an API as it affects productivity of the user and quality of code being return by programmer.

API designing takes into account various factors apart from just programming a business logic, like documentation, level of abstraction, error handling, dependencies etc.

Before diving deep into API Design, it's important to understand and classify API types.

These kinds of APIs are used in web applications. They here are based on REST, SOAP, XML-RPC and JSON-RPC standards. RESTful APIs are popular nowadays, RESTful Web Services are any of a group of approaches that conform to the principles of Representational State Transfer (REST) architecture. REST principles call for stateless client/server architecture typically based on HTTP. They conform to the use of Universal Resource Indicators (URIs) and use the CRED methods of PUT, GET, POST and DELETE. Resources are represented and therefore decoupled from their source. Messages are self-descriptive. Stateful interactions are achieved through hyperlinks. Since all interactions with resources are stateless because the requesting message is self-contained. Explicit state transfer is used to achieve stateful interactions. Transfer XML or JSON are used.^[6]

Source code APIs offer libraries of objects, classes, etc. Source code APIs are often used in development projects to create a composite application. The calls are made according to the standards of the application environment such as J2EE or .NET.^[6]

A variety of legacy approaches to application interfaces employ flat files, remote object protocols, operating system interfaces, hardware APIs, communication protocols, message queues and other means. Referring to these as legacy is not meant to be a pejorative, but rather a way of grouping a variety of long-standing and established, albeit somewhat older protocols together. A good example of a legacy API type would be (COMMON Object Request Broker Architecture) CORBA. CORBA object types can occur in many instances. So while the customer object type does not change, each instance of the customer object type is associated through a token to its data.^[6]

Pre-requisites of the Skill

• Domain knowledge for which API is being designed.
• Clear understanding of Client use cases because it’s often difficult or impossible to change it later without breaking client’s code.
• Clear understanding and strict adherence to API Guidelines.
• Documentation Standard.
• Strong understanding of programming language environment.
• In case of Web APIs, knowledge and usage of standard error messages is encouraged.
• Security measures and Versioning.

Related Software Engineering Areas

Design of An API falls under more than one software engineering Knowledge Area.

• Requirement Engineering: Use cases for effective and usable API must be retrieved and understood before designing an API.
• Software Construction: Designing an API is more than just programming, it includes various phases like documentation, security, accessibility, usability etc.
• Software Testing: Designed APIs must be tested against the requirements, should reconsider design in case of unsatisfactory results.
• Software Maintenance: Future changes in API or API design must be anticipated and performed during Maintenance phase.

Rationale for Skill

• APIs are entry point to the system for both external users and system’s own frontend, designing a flexible and robust API is necessary to fulfill those needs.
• APIs should able to handle increased user base, for that, they must be designed to be scalable from prior as later changes in signature of an API can break code at Client’s system.
• APIs add a layer of abstraction to the underlying system and helps users to understand functionality better.
• APIs allow restricted access to the internal system which in turn make sure secure access

Roles for skill

• Software Engineer
• Backend Developer
• Requirement Engineer

Work Related to Skill

• Google has made their API design guidelines public which they were using for creating Cloud APIs and other Services APIs since 2014.
• Microsoft has their own design guidelines which can be used by anyone while designing a Web API.
• There are insightful video resources available which explores common practices, standards and principles of an API design and can be used as building blocks while designing an API.

Real-World Example/Scenario of Skill

1. Create a API using API builder tool of Postman.
2. Create and edit the API schema.
3. Setup a mock server for API testing.
4. Add or import documentation.
5. Add Test suite to the API.

Role of Academia or Industry in Cultivating the Skill

There has been significant work done by industry in terms of simplifying process of designing, managing, testing and deploying of an API in last decade.

• Apiary: They started the modern API design movement by making API definitions more than just about API documentation, allowing API designers to define APIs in the machine-readable API definition format API blueprint, then mock, share, and publish documentation via a cloud platform.^[5]
• Swagger: Swagger is a machine-readable API definition format that has built a number of tools around the specification, including an open source API design editor that allows you to design, import, and export APIs in JSON and YAML, then also generate server and client-side code, as well as interactive documentation.^[5]

There are plenty of courses available on platform like Coursera and Udemy which covers latest tools, technologies and standard in order to design robust and usable APIs.

Tools Supporting the Skill

There are plethora of open source and paid tools available to design, maintain, test and deploy an API.

• Swagger
• Linx
• Fiddler
• Postman
• RAML
• SpotLight
• Apiary
• Azure API Management
• Google Apigee API Management Platform
• IBM API Connect

Skill Self-Assessment

Score: 6

Reason for the score:

• I have only worked with Web APIs in past couple of years, specifically with RESTful APIs with Java, JavaScript and Python server environments.

References

1. L. Murphy, M. B. Kery, O. Alliyu, A. Macvean and B. A. Myers, "API Designers in the Field: Design Practices and Challenges for Creating Usable APIs," 2018 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC), Lisbon, 2018, pp. 249-258, doi: 10.1109/VLHCC.2018.8506523.
2. SWEBOK
3. J. Stylos and B. Myers, "Mapping the Space of API Design Decisions," IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC 2007), Coeur d'Alene, ID, 2007, pp. 50-60, doi: 10.1109/VLHCC.2007.44.
4. J. Stylos, "Informing API Design through Usability Studies of API Design Choices: A Research Abstract," Visual Languages and Human-Centric Computing (VL/HCC'06), Brighton, 2006, pp. 246-247, doi: 10.1109/VLHCC.2006.27.
5. API Industry Guide on API design
6. API Types, Wikipedia