90000 What is API: Definition, Specifications, Types, Documentation 90001 Reading time: 9 minutes 90002 If you ever read tech magazines or blogs, you’ve probably seen the abbreviation API. It sounds solid, but what does it mean and why should you bother? 90003
90002 Let’s start with a simple example: human communication. We can express our thoughts, needs, and ideas through language (written and spoken), gestures, or facial expressions.Interaction with computers, apps, and websites require user interface components — a screen with a menu and graphical elements, a keyboard, and a mouse. 90003
90002 Software or its elements do not need a graphical user interface to communicate with each other. Software products exchange data and functionalities via machine-readable interfaces — 90007 APIs (application programming interfaces). 90008 90003
90010 What is an API? 90011
90002 An 90013 API 90014 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. 90003
90002 90007 90008 90003
90002 90007 How API works. Source: 90008 90007 Medium 90008 90003
90002 Application programming interfaces consist of two components: 90003
90028
90029 Technical specification describing the data exchange options between solutions with the specification done in the form of a request for processing and data delivery protocols 90030
90029 Software interface written to the specification that represents it 90030
90033
90002 The software that needs to access information (i.e., X hotel room rates for certain dates) or functionality (ie, a route from point A to point B on a map based on a user’s location) from another software, calls its API while specifying the requirements of how data / functionality must be provided. The other software returns data / functionality requested by the former application. 90003
90002 And the interface by which these two applications communicate is what the API specifies. 90003
90002 The Red Hat specialists note that APIs are sometimes considered contracts, where documentation is an agreement between the parties: 90007 «If party first sends a remote request structured a particular way, this is how the second party’s software will respond.»90008 The API documentation is a manual for developers that includes all necessary information on how to work with the API and use the services it provides. We will talk more about the documentation in one of the next sections. 90003
90002 Each API contains and is implemented by 90013 function calls 90014 — language statements that request software to perform particular actions and services. Function calls are phrases composed of verbs and nouns, for example: 90003
90028
90029 Start or finish a session 90030
90029 Get amenities for a single room type 90030
90029 Restore or retrieve objects from a server.90030
90033
90002 Function calls are described in the API documentation. 90003
90002 APIs serve numerous purposes. Generally, they can simplify and speed up software development. Developers can add functionality (i.e., recommender engine, accommodation booking, image recognition, payment processing) from other providers to existing solutions or build new applications using services by third-party providers. In all these cases, specialists do not have to deal with source code, trying to understand how the other solution works.They simply connect their software to another one. In other words, APIs serve as an abstraction layer between two systems, hiding the complexity and working details of the latter. 90003
90010 Types of APIs 90011
90060 APIs by availability aka release policies 90061
90002 In terms of release policies, APIs can be private, partner, and public. 90003
90002 90003
90002 90007 Types of APIs by availability 90008 90003
90002 90013 Private APIs. 90014 These application software interfaces are designed for improving solutions and services within an organization.In-house developers or contractors may use these APIs to integrate a company’s IT systems or applications, build new systems or customer-facing apps leveraging existing systems. Even if apps are publicly available, the interface itself remains available only for those working directly with the API publisher. The private strategy allows a company to fully control the API usage. 90003
90002 90013 Partner APIs. 90014 Partner APIs are openly promoted but shared with business partners who have signed an agreement with the publisher.The common use case for partner APIs is software integration between two parties. A company that grants partners with access to data or capability benefits from extra revenue streams. At the same time, it can monitor how the exposed digital assets are used, ensure whether third-party solutions using their APIs provide decent user experience, and maintain corporate identity in their apps. 90003
90002 90013 Public APIs. 90014 Also known as developer-facing or external, these APIs are available for any third-party developers.A public API program allows for increasing brand awareness and receiving an additional source of income when properly executed. 90003
90002 There are two types of public APIs — open (free of charge) and commercial ones. The Open API Definition suggests that all features of such an API are public and can be used without restrictive terms and conditions. For instance, it’s possible to build an application that utilizes the API without explicit approval from the API supplier or mandatory licensing fees.The definition also states that the API description and any related documentation must be openly available, and that the API can be freely used to create and test applications. 90003
90002 Commercial API users pay subscription fees or use APIs on a pay-as-you-go basis. A popular approach among publishers is to offer free trials, so users can evaluate APIs before purchasing subscriptions. 90003
90060 APIs by use cases 90061
90002 APIs can be classified according to the systems for which they are designed.90003
90002 90013 Database APIs. 90014 Database APIs enable communication between an application and a database management system. Developers work with databases by writing queries to access data, change tables, etc. The Drupal 7 Database API, for example, allows users to write unified queries for different databases, both proprietary and open source (Oracle, MongoDB, PostgreSQL, MySQL, CouchDB, and MSSQL). 90003
90002 Another example is ORDS database API, which is embedded into Oracle REST Data Services.90003
90002 90013 Operating systems APIs. 90014 This group of APIs defines how applications use the resources and services of operating systems. Every OS has its set of APIs, for instance, Windows API or Linux API (kernel-user space API and kernel internal API). 90003
90002 Apple provides API reference for macOS and iOS in its developer documentation. APIs for building applications for Apple’s macOS desktop operating system are included in the Cocoa set of developer tools. Those building apps for the iOS mobile operating system use Cocoa Touch — a modified version of Cocoa.90003
90002 90013 Remote APIs. 90014 Remote APIs define standards of interaction for applications running on different machines. In other words, one software product accesses resources located outside the device that requests them, which explains the name. Since two remotely located applications are connected over a communications network, particularly the internet, most remote APIs are written based on web standards. Java Database Connectivity API and Java Remote Method Invocation API are two examples of remote application programming interfaces.90003
90002 90013 Web APIs. 90014 This API class is the most common. 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). 90003
90002 Developers can use web APIs to extend the functionality of their apps or sites. For instance, the Pinterest API comes with tools for adding users ‘Pinterest data like boards or Pins to a website.Google Maps API enables the addition of a map with an organization’s location. 90003
90010 API specifications / protocols 90011
90002 The goal of API specifications is to standardize data exchange between web services. In this case, standardization means the ability of diverse systems, written in different programming languages ββand / or running on different OSs, or using different technologies, to seamlessly communicate with each other. 90003
90002 Several API specifications are in place. 90003
90060 Remote Procedure Call (RPC) 90061
90002 Web APIs may adhere to resource exchange principles based on a Remote Procedure Call.This protocol specifies the interaction between client-server based applications. One program (client) requests data or functionality from another program (server), located in another computer on a network, and the server sends the required response. 90003
90002 RPC is also known as a subroutine or function call. One of two ways to implement a remote procedure call is SOAP. 90003
90060 Service Object Access Protocol (SOAP) 90061
90002 SOAP is a lightweight protocol for exchanging structured information in a decentralized, distributed environment, according to the definition by Microsoft that developed it.Generally speaking, this specification contains the syntax rules for request and response messages sent by web applications. APIs that comply with the principles of SOAP enable XML messaging between systems through HTTP or Simple Mail Transfer Protocol (SMTP) for transferring mail. 90003
90002 Extensible markup language (XML) is a simple and very flexible text format widely used for data storage and exchange over the internet or other networks. XML defines a set of rules for encoding documents in a format that both humans and machines can read.The markup language is a collection of symbols that can be placed in the text to delineate and label the parts of the text document. XML text documents contain self-descriptive tags of data objects, which makes them easily readable. 90003
90002 90013 90014 90003
90002 90007 An example of a SOAP XML request call in Google Ad Manager. Source: 90008 90007 Google Ad Manager 90008 90003
90002 SOAP is mostly used with enterprise web-based software to ensure high security of transmitted data.SOAP APIs are preferred among providers of payment gateways, identity management and CRM solutions, as well as financial and telecommunication services. PayPal’s public API is one of the commonly known SOAP APIs. It’s also frequently used for legacy system support. 90003
90060 Representational State Transfer (REST) ββ90061
90002 The term 90007 REST 90008 was introduced by computer scientist Roy Fielding in a dissertation in 2000. Unlike SOAP, which is a protocol, REST is a software architectural style with six constraints for building applications that work over HTTP, often web services.The World Wide Web is the most common realization and application of this architecture style. 90003
90002 REST is considered a simpler alternative to SOAP, which many developers find difficult to use because it requires writing a lot of code to complete every task and following the XML structure for every message sent. REST follows another logic since it makes data available as resources. Each resource is represented by a unique URL, and one can request this resource by providing its URL. 90003
90002 Web APIs that comply with REST architectural constraints are called RESTful APIs.These APIs use HTTP requests (AKA methods or verbs) to work with resources: GET, PUT, HEAD, POST, PATCH, CONNECT, TRACE, OPTIONS and DELETE. 90003
90002 RESTful systems support messaging in different formats, such as plain text, HTML, YAML, XML, and JSON, while SOAP only allows XML. The ability to support multiple formats for storing and exchanging data is one of the reasons REST is a prevailing choice for building public APIs these days. 90003
90002 Social media giants and travel companies provide external APIs to improve their brand visibility even more.Twitter has numerous RESTful APIs; Expedia has both SOAP and RESTful APIs for its partners. If you consider redefining your travel and hospitality business offering, dive deep into the world of travel and booking APIs with our dedicated article. 90003
90002 JavaScript Object Notation (JSON) is a lightweight and easy-to-parse text format for data exchange. Its syntax is based on a subset of the Standard ECMA-262 3rd Edition. Each JSON file contains collections of name / value pairs and ordered lists of values.Since these are universal data structures, the format can be used with any programming language. 90003
90002 90003
90002 90007 A GET request for restaurant details with a response in JSON. Source: 90008 90007 OpenTable 90008 90003
90002 JSON has been widely adopted thanks to the popularity of REST. 90003
90060 GraphQL 90061
90002 The need for faster feature development, more efficient data loading due to increased mobile adoption, and a multitude of clients, made the developers look for other approaches to software architecture.GraphQL, initially created by Facebook in 2012 for internal use, is the new REST with organizations like Shopify, Yelp, GitHub, Coursera, and 90007 The New York Times 90008 using it to build APIs. 90003
90002 GraphQL is a query language for APIs. It allows the client to detail the exact data it needs and simplifies data aggregation from multiple sources, so the developer can use one API call to request all needed data. Another special feature of GraphQL is that it uses a 90007 type system 90008 to describe data.90003
90002 90003
90002 90007 Using types to describe data allows apps to specify what data they need to get 90008 90003
90002 Apps using GraphQL control what data they need to fetch from a server, which allows them to run fast even when the mobile connection is slow. 90003
90010 API documentation 90011
90002 No matter how many opportunities for creating or extending software products API gives, it would remain an unusable piece of code if developers did not understand how to work with it.Well-written and structured API documentation that explains how to effectively use and integrate an API in an easy-to-comprehend manner will make a developer happy and eager to recommend the API to peers. 90003
90002 The API documentation is a reference manual with all needed information about the API, including functions, classes, return types, and arguments. 90003
90002 Numerous content elements make good documentation, such as: 90003
90028
90029 a quick start guide 90030
90029 authentication information 90030
90029 explanations for every API call (request) 90030
90029 examples of every request and return with a response description, error messages, etc.90030
90029 samples of code for popular programmatic languages ββlike Python, Java, JavaScript, or PHP; 90030
90029 tutorials 90030
90029 SDK examples (if SDKs are available) illustrating how to access the resource, etc. 90030
90033
90002 Documentation may be 90007 static 90008 and 90007 interactive. 90008 The latter allows for trying out APIs and see return results and usually consists of two columns: human and machine. The human column contains API descriptions, and the machine one has a console to make calls and contains info that clients and servers will be interested in when testing the API.90003
90002 90003
90002 90007 Human and machine columns in the documentation Code examples on the machine column (right) after a user clicked for an action ( «Get all employees»). Source: 90008 90007 AMIS 90008 90003
90002 Generation is the process of documenting APIs by developers and technical writers. The specialists may use API documentation solutions (i.e., Swagger tools, Postman, Slate, or ReDoc) to unify documentation structure and design. 90003
90010 Final word 90011
90002 The role of APIs is considerably greater if we look at it not only from the software development angle but also from the business collaboration angle.These machine-readable interfaces for resource exchange are like delivery services that work under the hood and enable that needed technological connectivity. More than 60 percent of the participants in the Current State of API Integration 2018 report agreed that API integration is critical to their business strategy. The study also suggested over 50 percent of all businesses would partner via APIs. 90003
90002 In this regard, the two main tasks for decision makers and developers are to select the API that works for a company’s specific business needs and understand how to effectively use it.90003
.90000 java — What exactly is a Specification? 90001
Stack Overflow 90002
90003
Products
90004 90003
Customers
90004
90003
Use cases
90004
90009
90010
90003
Stack Overflow
Public questions and answers
90004
90003
Teams
Private questions and answers for your team
90004
90003
Enterprise
Private self-hosted questions and answers for your enterprise
90004
90003
Jobs
Programming and related technical career opportunities
90004
90003
Talent
Hire technical talent
90004
90003
Advertising
Reach developers worldwide
90004 90009
.90000 full text search — Jpa Specification can not call contains function 90001
Stack Overflow 90002
90003
Products
90004 90003
Customers
90004
90003
Use cases
90004
90009
90010
90003
Stack Overflow
Public questions and answers
90004
90003
Teams
Private questions and answers for your team
90004
90003
Enterprise
Private self-hosted questions and answers for your enterprise
90004
90003
Jobs
Programming and related technical career opportunities
90004
90003
Talent
Hire technical talent
90004
90003
Advertising
Reach developers worldwide
90004 90009
.90000 What is the difference between a Requirement and a Specification? 90001 90002 Browse: 90003
90004 90002 What is the difference between a Requirement and a Specification? 90003
90007 by Ivy Hooks 90008
90007 I have been asked this question, or some variation of it, many times. This question is akin to asking, «What is the difference between a sentence and a book?». This does not seem to be a difficult question, but why would someone ask it? One should answer this question only after determining the questioner’s view of a book.Is a book referring to something like a textbook or a novel? Is it a set of records such as a ledger? Or is it used as a betting term «make book»? Most people would assume the first definition and answer the question accordingly. Assumptions cause problems and good requirement writers avoid assumptions. 90008
90007 Answering the question about the difference between a requirement and a specification first requires that the person asking the question and the person answering the question share a common understanding of the terminology for different deliverables in the requirement development process.By clarifying some common terms, I believe I can provide answers to the original question as well as a number of related questions, which have all been restated from the original and seem similar, but are actually very different: 90008
90013
90014 What is the difference between a Requirement and a Requirement Specification? 90015
90014 What is the difference between a Requirement Specification and a Design Specification? 90015
90014 What is the difference between a Requirement and an existing product’s Spec Sheet? 90015
90020
90007 The first step to answering these questions is to define some terms and the way they are used in combination with each other.90008
90023 Understanding «First Names» and «Last Names» 90024
90007 First, let me introduce two «last names»: Document and Specification. The engineering world has used the term «Specification» for many decades combined with a set of first names related to the product life-cycle. Among software organizations, the term has been replaced by «Document». In the requirement world, these are virtually interchangeable and can often be found with identical first names. For example: 90008
90027
90014 Requirement Document versus Requirement Specification 90015
90014 Design Document versus Design Specification 90015
90032
90007 I recommend you do not concern yourself with the last names.Either a «Document» or a «Specification» is a collection of information about a product at various times in the product life-cycle. First names, on the other hand, relate to a point in the life-cycle. 90008
90035
90036
90037 90038 First Names 90039 90040
90037 90038 Information which describes a product’s … 90039 90040
90045
90036
90037 Requirement 90040
90037 Functions, performance, qualities, and constraints — the «what» to guide the design 90040
90045
90036
90037 Design or End-item 90040
90037 Architecture and the technical «how» to meet the requirements and to guide the builders or coders 90040
90045
90036
90037 As-Built 90040
90037 Final delivered configuration and technical information 90040
90045
90036
90037 Test or Verification 90040
90037 Proof that it meets the requirements 90040
90045
90070
90007 90038 Example: 90039 90008
90007 The following examples are generalizations.There are organizations that always use the term «Document», while others always use the term «Specification», and others use both. 90008
90007 If developing an engineering product, you might have 90008
90027
90014 a Product Requirement Specification (PRS), 90015
90014 a Product Design Specification (PDS) or End-Item Spec (EIS), and 90015
90014 a Product Test Specification (PTS). 90015
90032
90007 If developing software product, you might have 90008
90027
90014 a Product Requirement Document (PRD), 90015
90014 a Product Design Document (PDD), and 90015
90014 a Product Test Document (PTD).90015
90032
90007 The purpose of a PRS is the same as that of a PRD; of a PDS as a PDD, and of a PTS as a PTD. The purpose of the specification and the document is the same if their first name is identical. However, the content and organization will vary based on the type of product (i.e. system versus software and hardware versus software). 90008
90007 It is not a good use of your time to debate the correctness or incorrectness of an organization’s use of these «last names». It is important to know what to use for a particular project and move on.90008
90023 Restating the Question 90024
90007 I can now restate the original question, «What is the difference between a Requirement and a Specification?», Using these terms. The term used below is «Specification», but you can substitute «Document», if that is your terminology. 90008
90007 90038 1. What is the difference between a Requirement and a Requirement Specification? 90039 90008
90007 A Requirement is a statement of one thing a product must do or a quality it must have. A Requirement Specification is a collection of the set of all requirements that are to be imposed on the design and verification of the product.The specification also contains other related information necessary for the design, verification, and maintenance of the product. 90008
90007 There are requirements for things other than products, such as services, but in this discussion we are restricting our answers to products. 90008
90007 90038 2. What is the difference between a Requirement Specification and a Design Specification? 90039 90008
90007 A Requirement Specification addresses the 90118 «what» 90119, and a Design Specification addresses the 90118 «how» 90119.In a perfect world, the Requirement Specification precedes the Design Specification, and each is written by different people with different knowledge and viewpoints. 90008
90007 Stakeholders communicate the requirements that the product must be designed to meet through the set of requirements in the Requirement Specification. This provides guidance to the design team. 90008
90007 The Requirement Specification should state 90118 what 90119 the various stakeholders of the product need in terms of features, functions, performance, constraints, and quality, written in terms of what the product must do or qualities it must have.These stakeholders, including customers, users, maintenance, tech support and others, have the knowledge to define these requirements. Sometimes these stakeholders state their requirements in terms of design, often unintentionally. There are requirement best practices for correcting this problem and for giving the designers the latitude to define the best solution. 90008
90007 The 90038 Design Specification 90039 (sometimes known as the End-Item Spec) reflects the design and provides directions to the builders and coders of the product.Through this document, designers communicate the design for the product to which the builders or coders must comply. 90008
90007 The Design Specification should state 90118 how 90119 the design will meet the requirements. Design is not a one-to-one response to requirements. Design requires discipline knowledge and integration of disciplines in most cases. Design will be concerned with trade-offs — between different approaches to meet the requirements and concerning issues such as build or buy.The Design Specification will contain information about the product architecture and describe how each component will contribute to meeting the requirements. 90008
90007 90038 3. What is the difference between a Requirement and an existing product’s Spec Sheet? 90039 90008
90007 Commercial off-the-shelf (COTS) products have Spec Sheets that contain the major functions and features of each item in a product line. This enables a consumer, whether personal or business, to research the best fit for their requirements.You need requirements even if you are purchasing a COTS product. The number of requirements is generally much smaller for a COTS product than for a new product design. For a COTS product, you are restricted to what is commercially available for the particular type product that you have in mind. 90008
90007 The illustrations below describe personal decisions, but the same situation exists when you are buying COTS items for commercial reasons, including COTS components that you will use in a product that you are building.90008
90007 90146 Example 1 — You need a new refrigerator. 90147 90008
90007 You will look at the specs for different refrigerators that can fit into your available space, have the features that are important to you, and are within your price range. These are your requirements, and you are looking to see who has built something that meets your requirements. Manufacturers know that there are certain refrigerator requirements of concern to any and all customers — from price, to dimensions, to electrical consumption, to exterior finish and interior configuration.They create a spec sheet for each of their products so that you can shop for the model that best meets your requirements. Everything you care about is probably on that spec sheet, with some exceptions, and there will be things there that are of no concern to you. There may be items on the spec sheet you had not considered, but upon seeing them listed, you realize you really do care (such as having a water dispenser in the door or not). The manufacturer’s spec sheet helps you think of those things you forgot to specify.90008
90007 90146 Example 2 — You are shopping for a new laptop. 90147 90008
90007 Prime requirements might be weight, size of memory and speed. Computer manufacturers create spec sheets to cover almost all customer concerns in order to make shopping for the right model easier. You have probably used on-line programs that let you «compare» items. 90008
90007 90038 Do you have a «requirement» question you would like the Requirements Experts team to address? 90039 If so, please visit www.reqexperts.com and contact us. 90008
90023 About the Author, Ivy Hooks 90024
90007 90008
90007 The former CEO and a founder of Requirements Experts, Ivy Hooks is an internationally recognized expert on the subjects of requirements engineering and requirement management. Ivy has published papers in a number of journals and proceedings and has spoken to diverse audiences worldwide. She has also provided training and consulting to multiple government and commercial organizations for over 20 years.90008
90007 Ivy’s NASA career took her from the Apollo program through the Space Shuttle Program. She was a member of the initial Shuttle design team and managed the development of the separation systems and the verification of the flight software. 90008
90007 You might also find interesting: 90008 .
ΠΠ± Π°Π²ΡΠΎΡΠ΅