Application Programming
Interface
“API”
Contents
What is an API?
Types of API’s
API Specifications/Protocols
API Documentations
What is an API?
APIs are mechanisms that enable two software components to
communicate with each other using a set of definitions and
protocols.
واﺟﻬﺎت اﻟﺘﻄﺒﻴﻘﺎت اﻟﺒﺮﻣﺠﻴﺔ ﻫﻲ آﻟﻴﺎت ﺗﻤﻜﻦ ﻣﻜﻮﻧﻴﻦ ﻣﻦ اﻟﺒﺮاﻣﺞ ﻣﻦ اﻟﺘﻮاﺻﻞ ﻣﻊ ﺑﻌﻀﻬﻤﺎ
.اﻟﺒﻌﺾ ﺑﺎﺳﺘﺨﺪام ﻣﺠﻤﻮﻋﺔ ﻣﻦ اﻟﺘﻌﺮﻳﻔﺎت واﻟﺒﺮوﺗﻮﻛﻮﻻت
What is an API?
In the context of APIs, the word Application refers to any
software with a distinct function. Interface can be thought of as
a contract of service between two applications. This contract
defines how the two communicate with each other using requests
and responses. Their API documentation contains information on
how developers are to structure those requests and responses.
. ﺗﺸﻴﺮ ﻛﻠﻤﺔ "ﺗﻄﺒﻴﻖ" إﻟﻰ أي ﺑﺮﻧﺎﻣﺞ ﻟﻪ وﻇﻴﻔﺔ ﻣﻤﻴﺰة، ﻓﻲ ﺳﻴﺎق واﺟﻬﺎت ﺑﺮﻣﺠﺔ اﻟﺘﻄﺒﻴﻘﺎت
ﻳﺤﺪد ﻫﺬا اﻟﻌﻘﺪ ﻛﻴﻒ ﻳﺘﻮاﺻﻞ اﻻﺛﻨﺎن ﻣﻊ.ﻳﻤﻜﻦ اﻋﺘﺒﺎر اﻟﻮاﺟﻬﺔ ﺑﻤﺜﺎﺑﺔ ﻋﻘﺪ ﺧﺪﻣﺔ ﺑﻴﻦ ﺗﻄﺒﻴﻘﻴﻦ
اﻟﺨﺎﺻﺔ ﺑﻬﻢ ﻋﻠﻰ ﻣﻌﻠﻮﻣﺎت ﺣﻮلAPI ﺗﺤﺘﻮي وﺛﺎﺋﻖ.ﺑﻌﻀﻬﻤﺎ اﻟﺒﻌﺾ ﺑﺎﺳﺘﺨﺪام اﻟﻄﻠﺒﺎت واﻟﺮدود
.ﻛﻴﻔﻴﺔ ﻗﻴﺎم اﻟﻤﻄﻮرﻳﻦ ﺑﻬﻴﻜﻠﺔ ﺗﻠﻚ اﻟﻄﻠﺒﺎت واﻻﺳﺘﺠﺎﺑﺎت
Types of API’s
There are mainly four main types of APIs:
● Open APIs: These types of APIs are publicly available to
use like OAuth APIs from Google. It has also not given
any restriction to use them. So, they are also known as
Public APIs.
● Partner APIs: Specific rights or licenses to access this
type of API because they are not available to the public.
Types of API’s
There are mainly four main types of APIs:
● Internal APIs: Internal or private. These APIs are
developed by companies to use in their internal systems.
It helps you to enhance the productivity of your teams.
● Composite APIs: This type of API combines different data
and service APIs.
API Specifications/Protocols
The protocol defines how your API connects to the internet
and how it communicates information. The protocol you choose
will determine how you design and build your API, as well as
what’s required to maintain it.
. اﻟﺨﺎص ﺑﻚ ﺑﺎﻹﻧﺘﺮﻧﺖ وﻛﻴﻔﻴﺔ ﺗﻮﺻﻴﻞ اﻟﻤﻌﻠﻮﻣﺎتAPI ﻳﺤﺪد اﻟﺒﺮوﺗﻮﻛﻮل ﻛﻴﻔﻴﺔ اﺗﺼﺎل
، ﺳﻴﺤﺪد اﻟﺒﺮوﺗﻮﻛﻮل اﻟﺬي ﺗﺨﺘﺎره ﻛﻴﻔﻴﺔ ﺗﺼﻤﻴﻢ واﺟﻬﺔ اﻟﺘﻄﺒﻴﻘﺎت اﻟﺒﺮﻣﺠﻴﺔ وإﻧﺸﺎﺋﻬﺎ
.ﺑﺎﻹﺿﺎﻓﺔ إﻟﻰ ﻣﺎ ﻫﻮ ﻣﻄﻠﻮب ﻟﺼﻴﺎﻧﺘﻬﺎ
API Specifications/Protocols
● The REpresentational State Transfer (REST or
RESTful) protocol
● The Simple Object Access Protocol (SOAP)
● The Remote Procedure Call (RPC) protocol
● GraphQL
SOAP APIs
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.
SOAP APIs
One major advantage of SOAP is that it requires metadata
files describing requests, which makes exchanges more
predictable. It also enables stateful requests, unlike
REST, which is stateless.
In general, SOAP is a better fit for more sophisticated
applications, where reliability is more important than
speed or usability by a public audience. As a result,
it’s widely used in financial services and in large
enterprise applications like Salesforce.
SOAP APIs
ﺗﺘﻤﺜﻞ إﺣﺪى اﻟﻤﻴﺰات اﻟﺮﺋﻴﺴﻴﺔ ﻟ SOAPﻓﻲ أﻧﻬﺎ ﺗﺘﻄﻠﺐ ﻣﻠﻔﺎت ﺑﻴﺎﻧﺎت وﺻﻔﻴﺔ ﺗﺼﻒ
اﻟﻄﻠﺒﺎت ،ﻣﻤﺎ ﻳﺠﻌﻞ اﻟﺘﺒﺎدﻻت أﻛﺜﺮ ﻗﺎﺑﻠﻴﺔ ﻟﻠﺘﻨﺒﺆ .ﻛﻤﺎ أﻧﻪ ﻳﻤﻜّﻦ اﻟﻄﻠﺒﺎت ذات اﻟﺤﺎﻟﺔ
،ﻋﻠﻰ ﻋﻜﺲ ، RESTﻋﺪﻳﻤﺔ اﻟﺤﺎﻟﺔ .ﻳﺴﻤﺢ وﺟﻮد ﺑﺮوﺗﻮﻛﻮل أﻛﺜﺮ ﺗﻮﺣﻴﺪًا ﻟﻮاﺟﻬﺎت
ﺑﺮﻣﺠﺔ ﺗﻄﺒﻴﻘﺎت SOAPﺑﺘﻮﺻﻴﻞ ﺑﻴﺎﻧﺎت أﻛﺜﺮ ﺗﻌﻘﻴﺪًا ﺑﺸﻜﻞ ﻣﻮﺛﻮق ،وﺗﻘﺪﻳﻤﻬﺎ ﻋﺒﺮ
ﻗﻨﻮات أﻛﺜﺮ ﻣﻦ HTTPﻓﻘﻂ .ﻳﻤﻜﻦ أن ﻳﺆدي اﺳﺘﺨﺪام SOAPﻟﻮاﺟﻬﺎت اﻟﺨﺪﻣﺔ
ﺑﺪﻻ ً ﻣﻦ اﻟﺘﻨﻈﻴﻢ اﻟﺒﺴﻴﻂ اﻟﻤﺴﺘﻨﺪ إﻟﻰ ﻋﻨﻮان URLإﻟﻰ زﻳﺎدة ﻗﺎﺑﻠﻴﺔ اﻻﻛﺘﺸﺎف
ﻟﻠﻤﺴﺘﺨﺪﻣﻴﻦ اﻟﻤﻄﻠﻌﻴﻦ .ﺑﺸﻜﻞ ﻋﺎم ،ﻳﻌﺪ SOAPﻣﻨﺎﺳﺒًﺎ ﺑﺸﻜﻞ أﻓﻀﻞ ﻟﻠﺘﻄﺒﻴﻘﺎت
اﻷﻛﺜﺮ ﺗﻌﻘﻴﺪًا ،ﺣﻴﺚ ﺗﻜﻮن اﻟﻤﻮﺛﻮﻗﻴﺔ أﻛﺜﺮ أﻫﻤﻴﺔ ﻣﻦ اﻟﺴﺮﻋﺔ أو ﺳﻬﻮﻟﺔ اﻻﺳﺘﺨﺪام
ﻣﻦ ﻗﺒﻞ اﻟﺠﻤﻬﻮر اﻟﻌﺎم .ﻧﺘﻴﺠﺔ ﻟﺬﻟﻚ ،ﻳﺘﻢ اﺳﺘﺨﺪاﻣﻪ ﻋﻠﻰ ﻧﻄﺎق واﺳﻊ ﻓﻲ
اﻟﺨﺪﻣﺎت اﻟﻤﺎﻟﻴﺔ وﺗﻄﺒﻴﻘﺎت اﻟﻤﺆﺳﺴﺎت اﻟﻜﺒﻴﺮة ﻣﺜﻞ .Salesforce
RPC APIs
The Remote Procedure Call (RPC) protocol can return
XML or JSON responses.
● RPC API works with actions.
● They are most often private APIs
● RPC’s URI identifies only the server.
REST APIs
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
architectural style.
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.
REST APIs
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.
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.
Constraints of the RESTful architecture
The six guiding principles or constraints of the RESTful
architecture are:
● Uniform Interface
● Client-Server
● Stateless
● Cacheable
● Layered System
● Code on Demand (Optional)
Constraints of the RESTful architecture
● Uniform Interface
By applying the principle of generality to the components
interface, we can simplify the overall system architecture
and improve the visibility of interactions.Multiple
architectural constraints help in obtaining a uniform
interface and guiding the behavior of components.
Constraints of the RESTful architecture
● Client-Server
The client-server design pattern enforces the separation of concerns,
which helps the client and the server components evolve independently.
By separating the user interface concerns (client) from the data storage
concerns (server), we improve the portability of the user interface across
multiple platforms and improve scalability by simplifying the server
components.
While the client and the server evolve, we have to make sure that the
interface/contract between the client and the server does not break.
Constraints of the RESTful architecture
● Stateless
Statelessness mandates that each request from the client
to the server must contain all of the information
necessary to understand and complete the request.
The server cannot take advantage of any previously stored
context information on the server.For this reason, the
client application
Constraints of the RESTful architecture
● Cacheable
The cacheable constraint requires that a response should
implicitly or explicitly label itself as cacheable or
non-cacheable.
If the response is cacheable, the client application gets
the right to reuse the response data later for equivalent
requests and a specified period.
Constraints of the RESTful architecture
● Layered System
The layered system style allows an architecture to be
composed of hierarchical layers by constraining component
behavior.
For example, in a layered system, each component cannot
see beyond the immediate layer they are interacting with.
Constraints of the RESTful architecture
● Code on Demand (Optional)
REST also allows client functionality to extend by
downloading and executing code in the form of applets or
scripts.
The downloaded code simplifies clients by reducing the
number of features required to be pre-implemented.
Servers can provide part of features delivered to the
client in the form of code, and the client only needs to
execute the code.
What is a Resource?
The key abstraction of information in REST is a resource. Any information that
we can name can be a resource. For example, a REST resource can be a document
or image, a temporal service, a collection of other resources, or a
non-virtual object (e.g., a person).
The state of the resource, at any particular time, is known as the resource
representation.
The resource representations are consist of:
● the data
● the metadata describing the data
● and the hypermedia links that can help the clients in transition to the
next desired state.
A REST API consists of an assembly of interlinked
resources. This set of resources is known as the REST
API’s resource model.
What is a Resource?
2.1. Resource Identifiers
REST uses resource identifiers to identify each resource involved in the
interactions between the client and the server components.
2.2. Hypermedia
The data format of a representation is known as a media type. The media type
identifies a specification that defines how a representation is to be processed.
A RESTful API looks like hypertext. Every addressable unit of information carries
an address, either explicitly (e.g., link and id attributes) or implicitly (e.g.,
derived from the media type definition and representation structure).
What is a Resource?
2.3. Self-Descriptive
resource representations shall be self-descriptive: the client does
not need to know if a resource is an employee or a device. It
should act based on the media type associated with the resource.
So in practice, we will create lots of custom media types – usually
one media type associated with one resource.
Every media type defines a default processing model. For example,
HTML defines a rendering process for hypertext and the browser
behavior around each element.
GraphQL APIs
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 type system to describe data.
ﻳﺴﻤﺢ ﻟﻠﻌﻤﻴﻞ ﺑﺘﻔﺼﻴﻞ اﻟﺒﻴﺎﻧﺎت اﻟﺪﻗﻴﻘﺔ. ﻫﻲ ﻟﻐﺔ اﺳﺘﻌﻼم ﻟﻮاﺟﻬﺎت ﺑﺮﻣﺠﺔ اﻟﺘﻄﺒﻴﻘﺎتGraphQL
ﺑﺤﻴﺚ ﻳﻤﻜﻦ ﻟﻠﻤﻄﻮر اﺳﺘﺨﺪام اﺳﺘﺪﻋﺎء، اﻟﺘﻲ ﻳﺤﺘﺎﺟﻬﺎ وﻳﺒﺴﻂ ﺗﺠﻤﻴﻊ اﻟﺒﻴﺎﻧﺎت ﻣﻦ ﻣﺼﺎدر ﻣﺘﻌﺪدة
ﻫﻲ أﻧﻬﺎ ﺗﺴﺘﺨﺪمGraphQL ﻣﻴﺰة أﺧﺮى ﺧﺎﺻﺔ ﻟ. واﺣﺪ ﻟﻄﻠﺐ ﺟﻤﻴﻊ اﻟﺒﻴﺎﻧﺎت اﻟﻤﻄﻠﻮﺑﺔAPI
.ﻧﻈﺎم ﻛﺘﺎﺑﺔ ﻟﻮﺻﻒ اﻟﺒﻴﺎﻧﺎت
API Documentations
The API documentation is a reference manual with all the
needed information about the API, including functions,
classes, return types, and arguments.
API Documentations
Numerous content elements make good documentation, such as:
● a quick start guide.
● authentication information.
● explanations for every API call (request).
● examples of every request and return with a response
description, error messages, etc.
● samples of code for popular programmatic languages like
Python, Java, JavaScript, or PHP
● tutorials.
● SDK examples (if SDKs are available) illustrating how to
access the resource, etc.
XML
XML (Extensible Markup Language) is used to describe data. The
XML standard is a flexible way to create information formats and
electronically share structured data via the public internet, as
well as via corporate networks.
XML's primary function is to create formats for data that is used
to encode information for documentation, database records,
transactions and many other types of data. XML data may be used
for creating different content types that are generated by
building dissimilar types of content -- including web, print and
mobile content -- that are based on the XML data.
XML
What Is Json?
JSON (JavaScript Object Notation) is the most widely used data format for data
interchange on the web. This data interchange can happen between two computer
applications at different geographical locations or running within the same
machine.
The good thing is that JSON is a human-readable as well as a machine-readable
format. So while applications/libraries can parse the JSON documents – humans
can also look at the data and derive the meaning from it.
All modern programming languages (e.g., Java, JavaScript, Ruby, C#, PHP,
Python, and Groovy) and application platforms provide excellent support for
producing (serializing) and consuming (deserializing) JSON data.
JSON Document
A JSON document may contain text, curly braces, square brackets, colons,
commas, double quotes, and maybe a few other characters.
Primarily, a valid JSON document can contain two structures:
● An Object surrounded by curly braces and containing multiple name/value
pairs. In various languages, this is realized as an record, struct,
dictionary, hash table, keyed list, or associative array.
● An Array or Ordered list of values surrounded by square brackets. In most
languages, this is realized as an vector, list, or sequence.
JSON Document
Thanks
