apies-type-of-api

API and type of Apis

In this post we  are going to talk about APIs and different type of APIs.

what is API?

APIs (application programming interfaces) come in many forms. API designers can choose from a range of protocols and standards when creating a new API, depending on the type of API they are creating, and its purpose. This article takes a look at a few important API types and protocols, including REST API protocols.

API Architectures and Protocols

An API protocol defines the rules for API calls: it specifies accepted data types and commands. Different API architectures specify different protocol constraints.

Type of API?

  • Web APIs
  • REST API
  • SOAP API
  • Composite APIs
  • Open APIs
  • Internal APIs
  • Partner APIs
  • GraphQL APIs

In the followings are description of each API.

WEB API

Web APIs are APIs that can be accessed using the HTTP protocol. The API defines endpoints, and valid request and response formats. Web APIs include the APIs used to communicate with the browser. They may be services such as web notifications and web storage. Different web APIs feature varying levels of security and privacy, including open, internal and partner APIs. Multiple web APIs can be combined into a composite API – a collection of data or service APIs.

Web API as the name suggests, is an API over the web which can be accessed using HTTP protocol. It is a concept and not a technology. We can build Web API using different technologies such as Java, .NET etc. For example, Twitter’s REST APIs provide programmatic access to read and write data using which we can integrate twitter’s capabilities into our own application.

ASP.NET Web API

The ASP.NET Web API is an extensible framework for building HTTP based services that can be accessed in different applications on different platforms such as web, windows, mobile etc. It works more or less the same way as ASP.NET MVC web application except that it sends data as a response instead of html view. It is like a webservice or WCF service but the exception is that it only supports HTTP protocol.

web-api-archtecture.png

ASP.NET Web API Characteristics

  1. ASP.NET Web API is an ideal platform for building RESTful services.
  2. ASP.NET Web API is built on top of ASP.NET and supports ASP.NET request/response pipeline
  3. ASP.NET Web API maps HTTP verbs to method names.
  4. ASP.NET Web API supports different formats of response data. Built-in support for JSON, XML, BSON format.
  5. ASP.NET Web API can be hosted in IIS, Self-hosted or other web server that supports .NET 4.0+.
  6. ASP.NET Web API framework includes new HttpClient to communicate with Web API server. HttpClient can be used in ASP.MVC server side, Windows Form application, Console application or other apps.

ASP.NET Web API vs WCF

WCF is Microsoft’s unified programming model for building service-oriented applications. It enables developers to build secure, reliable, transacted solutions that integrate across platforms and interoperate with existing investments. ASP.NET Web API is a framework that makes it easy to build HTTP services that reach a broad range of clients, including browsers and mobile devices. ASP.NET Web API is an ideal platform for building RESTful applications on the .NET Framework. This topic presents some guidance to help you decide which technology will best meet your needs.

When to choose WCF?

  • Choose WCF if you use .NET Framework 3.5. Web API does not support .NET 3.5 or below.
  • Choose WCF if your service needs to support multiple protocols such as HTTP, TCP, Named pipe.
  • Choose WCF if you want to build service with WS-* standards like Reliable Messaging, Transactions, Message Security.
  • Choose WCF if you want to use Request-Reply, One Way, and Duplex message exchange patterns.

When to choose ASP.NET Web API?

  • Choose Web API if you are using .NET framework 4.0 or above.
  • Choose Web API if you want to build a service that supports only HTTP protocol.
  • Choose Web API to build RESTful HTTP based services.
  • Choose Web API if you are familiar with ASP.NET MVC.

REST API and REST

REST (representational state transfer) is a very popular web API architecture. To be a REST API, an API must adhere to certain architectural constraints, or principles, including:

  • Client-server architecture: the interface is separated from the backend and data storage. This allows for flexibility, and for different components to evolve independent of each other.
  • Statelessness: no client context is stored on the server between requests.
  • Cacheability: clients can cache responses, so a REST API response must explicitly state whether it can be cached or not.
  • Layered system: the API will work whether it is communicating directly with a server, or through an intermediary such as a load balancer.

REST is basically an architectural style of the web services that work as a channel of communication between different computers or systems on the internet. The term REST API is something else.

Those application programming interfaces that are backed by the architectural style of REST architectural system are called REST APIs. REST API compliant web services, database systems, and computer systems permit requesting systems to get robust access and redefine representations of web based resources by deploying a predefined set of stateless protocols and standard operations.

By these protocols and operations and redeploying the manageable and updatable components without causing the effect on the system, REST API systems deliver fast performance, reliability, and more progression.

Open APIs

Open APIs, also known as external or public APIs, are available to developers and other users with minimal restrictions. They may require registration, and use of an API key, or may be completely open. They are intended for external users (developers at other companies, for example) to access data or services. As an example, take a look at the Food Hygiene Rating API provided by the UK government. Any developer can access it, without even registering, allowing app builders to include governmental data on restaurant standards in their apps.

Internal APIs

In contrast to open APIs, internal APIs are designed to be hidden from external users. They are used within a company to share resources. They allow different teams or sections of a business to consume each other’s tools, data and programs. Using internal APIs has several advantages over conventional integration techniques, including security and access control, an audit trail of system access, and a standard interface for connecting multiple services.

Partner APIs

Partner APIs are technically similar to open APIs, but they feature restricted access, often controlled through a third-party API gateway. They are usually intended for a specific purpose, such as providing access to a paid-for service. This is a very common pattern in software as a service ecosystem.

SOAP API

What is SOAP

SOAP (simple object access protocol) is an established web API protocol. It is intended to be extensible, neutral (able to operate over a range of communication protocols, including HTTP, SMTP, TCP and more), and independent (it allows for any programming style) The SOAP specification includes.

SOAP is a standard communication protocol system that permits processes using different operating systems like Linux and Windows to communicate via HTTP and its XML. SOAP based APIs are designed to create, recover, update and delete records like accounts, passwords, leads, and custom objects.

These offers over twenty different kinds of calls that make it easy for the API developers to maintain their accounts, perform accurate searches and much more. These can then be used with all those languages that support web services.

SOAP APIs take the advantages of making web based protocols such as HTTP and its XML that are already operating the all operating systems that are why its developers can easily manipulate web services and get responses without caring about language and platforms at all.

  • The processing model: how to process a SOAP message.
  • Extensibility model: SOAP features and modules.
  • Protocol binding rules: how to use SOAP with an underlying protocol, such as HTTP.
  • Message construct: how to structure a SOAP message.

SOAP is an important protocol that helped introduce the widespread use of Web Services, also called APIs. Based on XML, the SOAP protocol is still in wide usage. Many organizations use the more flexible REST API pattern, but others prefer the structure, datatype control, and defined standard of SOAP.

Among the important aspects of SOAP APIs are their independence from programming language and even underlying transport protocol. The sender can use C#, for example, while the recipient’s stack relies on Java. While these more enterprise-oriented languages are most common with SOAP, there are SOAP implementations in Python, Ruby, and all modern programming languages.

A final advantage to SOAP is its extensibility. As a standard, its specification is deliberately limited on constraints. As such, the extensibility model within the SOAP specification provides for customization.

How to Call a SOAP API

In order to call a SOAP API, you’ll most likely need to include a SOAP library with your programming language. Although it’s possible to make SOAP API calls without SOAP libraries, it’s more efficient to work with an abstraction rather than crafting the messages yourself. The SOAP messages are verbose, mainly due to reliance on XML.

Anatomy of a SOAP Message

In this section, you can better understand the few blocks of XML that SOAP requests contain. While it’s deliberately minimal (the “S” in SOAP stands for “simple,” after all), it provides the foundation for complex implementations.

SOAP messages are constructed of up to four blocks:

  • soap:Envelope
  • soap:Header
  • soap:Body
  • soap:Fault

Only soap:Envelope and soap:Body are required. However, each plays an important role in SOAP APIs. Below, each of these SOAP constructs is covered separately.

SOAP Envelope

SOAP uses XML, but needs a way to separate it from other XML documents. The soap:Envelope tag provides a mechanism to identify the XML as SOAP.

In addition, the soap:Envelope tag requires a namespace attribute (xmlns:soap="http://www.w3.org/2003/05/soap-envelope/" for the latest version of SOAP) and can optionally supply an encodingStyle attribute.

The entirety of the SOAP message comes within the envelope, including the other three blocks.

SOAP Header

In the basic SOAP API, the header is empty. While it’s optional, soap:Header makes possible SOAP’s extensibility via SOAP Modules. These modules can either be required or optional. In the case that they are required, you can include the mustUnderstand attribute set to true.

SOAP Body

As implied by the name and shown in examples, soap:Body contains the bulk of the SOAP message. Namespaces can be used to describe what data to expect within the body, but are not required. In practice, the name of the procedure, parameters, and data all come through the SOAP Body.

SOAP Fault

Finally, the soap:Fault tag is used within the soap:Body tag for error messages when a SOAP API call is not able to complete. There are many possible causes for an error, including inaccurate SOAP formatting, a processing error on the server, and mismatched data type.

To communicate the many errors, there are several sub-elements that can be present within the Fault tag:

  • Code: a machine-readable error code
  • Reason: a human-readable error reason
  • Node: the SOAP node where the error occurred
  • Role: the role of the SOAP node where the error occurred
  • Detail: application-specific error details, with both human- and machine-readable data

While soap:Fault is optional, a SOAP implementation is not truly complete without encapsulating potential errors using this tag.

Use a WSDL to Describe a SOAP API

As SOAP and other Web Services became ubiquitous, many tools, technologies, and standards were created to support them. Among them is the Web Services Description Language (WSDL), an XML format that describes how to call a web service. It defines the operations available and what input/output fields to expect.

Though not specific to SOAP, many implementations of SOAP APIs combine a WSDL with XML Schema to provide a robust web service for exchanging messages using defined procedures and field types. Because a WSDL is machine-readable, a SOAP client could determine what operations are possible, what data is needed to complete the call, and then present a user with the data needed.

WSDLs are also used to generate human-readable documentation for SOAP APIs. Developers can look at the method names and input to determine what’s required to call the SOAP API. In addition, some programming language libraries and developer environments can consume a WSDL file to help programmers with available methods and syntax when writing code.

Like SOAP, WSDL is general enough for many types of usage, though the two technologies are frequently used together.

SOAP API Security

Many SOAP API examples, such as those to query stock quotes or weather, have no authentication. While useful for a quick proof of concept, more robust SOAP APIs will authenticate and authorize the API calls, ensuring that important business processes are only available to approved parties.

As with any API or web service, there are many ways to handle security within SOAP APIs. Since many SOAP APIs use HTTP, it’s possible to piggyback on other authentication and authorization schemes within that protocol.

For example, HTTP Basic Auth accepts a username and password. When sent via SSL/TLS, this can be a barebones way to authenticate a user. However, there is no built-in role or authorization with this method. In addition, while it provides point-to-point security, often end-to-end security is required.

WS-Security is a SOAP extension that provides a number of security features for SOAP APIs. Built on top of the XML Encryption and XML Signature specifications, WS-Security describes how to sign and encrypt SOAP messages. In addition, it supports a handful of security token formats, including SAML, X.509, and Kerberos.

Perhaps SOAP’s most used extension, WS-Security enables end-to-end security, authorization of senders, and other features enterprises require in web services.

History and Future of SOAP

The first SOAP specification was published in 2000. An earlier version, released in 1998, was known as XML-RPC and had a more focused feature set. Like SOAP, XML-RPC allows for remote procedure calls via XML. XML-RPC specifically only uses HTTP to transport the data. While this is the common protocol for SOAP, as well, SOAP can technically use any protocol.

It took three years for the SOAP specification to reach recommendation stage. Quickly it became the most common approach to web services. Prior to SOAP, there was not a standards-based approach to creating programmable interfaces for exchanging data between systems. SOAP helped shepherd innovation both within the enterprise and encouraged the first wave of public APIs from companies like eBay, Salesforce, and Amazon.

Around the same time, REST APIs were described in a doctoral dissertation. However, SOAP’s embrace as a standard, as well as its application in industry (contrasted with academia), helped it remain the popular choice for much of the decade.

SOAP remains important as a standard for web services and runs many internal systems worldwide. For new projects, many organizations are moving to microservices architecture using REST APIs. While the more modern techniques leave behind a fully standards-based approach of SOAP, many prefer the more flexible and nimble development process.

 

Differences Between SOAP and REST

  • REST API has no official standard at all because it is an architectural style. SOAP API, on the other hand, has an official standard because it is a protocol.
  • REST APIs uses multiple standards like HTTP, JSON, URL, and XML while SOAP APIs is largely based on HTTP and XML.
  • As REST API deploys multiple standards, so it takes fewer resources and bandwidth as compared to SOAP that uses XML for the creation of Payload and results in the large sized file.
  • The ways both APIs exposes the business logics are also different. REST API takes advantage of URL exposure like @path(“/WeatherService”) while SOAP API use of services interfaces like @WebService.
  • SOAP API defines too many standards, and its implementer implements the things in a standard way only. In the case of miscommunication from service, the result will be the error. REST API, on the other hand, don’t make emphasis on too many standards and results in corrupt API in the end.
  • REST API uses Web Application Description Language, and SOAP API used Web Services Description language for describing the functionalities being offered by web services.
  • REST APIs are more convenient with JavaScript and can be implemented easily as well. SOAP APIs are also convenient with JavaScript but don’t support for greater implementation.

Similarities Between SOAP and REST

No matter which API format you lean towards, both SOAP and REST have some fundamental similarities:

  • Both SOAP and REST connect to two applications via server-side data that is machine and human-readable.
  • Both typically utilize HTTP protocols and methods (i.e. GET, POST, DELETE), but can also use other protocols, such as SMTP.
  • Both can understand XML web documentation and can use XML in requests and responses.

Despite the resemblance, there is little relation between providing or consuming SOAP and REST APIs.

When to Use SOAP vs REST

In short, SOAP and REST are two API formats that answer the question of data transmission from two different points of view.

REST has become the preferred choice for public APIs and open source work that allows other developers to connect and easily use the data. Its lighter architecture and allowance for JSON also leads to the faster performance speeds that mobile app designers covet.

Because of SOAP’s acceptance as a standard protocol, it also has advanced security features available via SOAP extensions. SOAP APIs forgo performance speed for higher complexity. Many large enterprises build SOAP APIs specifically for these reasons. However, there are many industry best practices for securing REST APIs, as well.

You may want to consider SOAP if the API consumers (your organization or partners) already have tooling that supports it. For example, C# and Java have advanced SOAP libraries. Similarly, you might need SOAP for its use of typed data and procedures. For example, you can call a remote procedure in SOAP similar to how you call a local procedure.

REST might be your ticket if you prefer JSON, would like a more simple code base that uses HTTP’s GET/POST/DELETE commands, and/or is more scalable, allowing your API to grow as your project does.

GraphQL APIs

What does GraphQL mean?

GraphQL stands for “Graph Query Language.” Let’s unpack what we mean by “graph” and “query language.

GraphQL is language-agnostic, which means it can be used with any backend framework or programming language, and is essentially an addition to a backend service that allows developers to communicate with the database and request data in a specific way.

To create a GraphQL server for your data source, you can use specialized tools such as ApolloGraphQL, which allow you to create a layer on top of your backend and database(s), enabling your data to be represented, queried and changed via the Graph Query Language.

More about GraphQL..

A brief history of GraphQL

GraphQL is a language used to communicate with backend systems, allowing you to fetch and manipulate your data. It was developed by Facebook in 2012, and released to the public in 2015. In 2019, the project was moved to the non-profit GraphQL Foundation, with a mission to ensure that the GraphQL community is able to focus on its continued evolution on a neutral platform.

Composite APIs

Composite APIs allow developers to access several endpoints in one call. These could be different endpoints of a single API, or they could be multiple services or data sources. Composite APIs are especially useful in microservice architectures, where a user may need information from several services to perform a single task. Using composite APIs can reduce server load and improve application performance, as one call can return all the data a user needs.

What is a Composite API?

Composite APIs are a design approach to batch API requests sequentially into a single API call. Rather than multiple round trips to a server, a client can make one API request with a chain of calls and receive one response.

For example, to create an order within a shopping cart API, you may require several endpoints:

  • Create customer
  • Create order for customer
  • Add item to order
  • Add another item
  • Change order status

While it is useful to have granular access to call a subset of the above sequence, together they comprise a common shopping cart use case. In order to fulfill an order, you’ll need to make these calls in succession.

A composite API provides a design solution that is more efficient for the client. Instead of five or more requests, there is only one. Rather than parsing five or more responses, all the necessary data is passed at the end of the sequence.

The structure of the composite response echos the request. There’s a top-level success field followed by an object that contains an array of individual responses. Each step includes ref, body, success, and status fields.

This example makes a lot of assumptions about how you might design your own composite APIs. The next section covers some of the elements to consider.

How to Design a Composite API

Most likely, your composite API will be a single endpoint to which you’ll POST your sequence of requests. Even with these criteria, you have some considerations for your composite API design:

  • Request representation: At a minimum, you need an array of objects that include the endpoint, method, and a way to pass data or parameters with each request.
  • Authentications: Will credentials be passed from the composite call to individual requests, or do you also need granular authentication for each underlying call?
  • Response rendering: You need to at least include the response from the final request. Likely, you also need to include some subset of response data from previous steps.
  • Field references: Sequential calls will be most useful if they can include data from earlier steps, which means you’ll need to determine how to structure those references.
  • Error handling: If one or more calls in your sequence returns an error, you’ll need to provide details to help consumers debug the response.
  • Partial successes: In addition to reporting errors, you’ll need to decide whether to continue the steps after the error.
  • All or none: Some use cases might also expect transactional features, where an error “rolls back” any changes in previous steps.

The decisions you make based on the above considerations will impact the design of your composite API. How you support composite calls will be determined by the use cases you expect.

Composite & Rest APIs

REST APIs are a popular convention, but they can be inefficient for some use cases. With a design around specific resources, multiple calls are often needed to support a single use case. Composite APIs are a potential architectural answer that can bundle multiple calls into a single API request.

Batch APIs vs Composite APIs

Depending on your needs, a batch API may meet the use cases you would otherwise point to a composite API. At first glance, they may seem similar. In fact, a composite API fulfills the requirements of a batch API, but the opposite is not true.

Batch APIs group API calls that aren’t necessarily related. For example, rather than making 10 API calls to create 10 new customers, a batch API endpoint would achieve the same result in a single call.

Some key differences in batch APIs make them easier to implement:

  • A subset of calls can fail without impacting the others
  • Subsequent calls do not need to reference previous data
  • If a call fails, there is no need to roll back changes made by earlier steps

Composite APIs provide a larger number of use cases, so they will likely be more powerful for consumers. However, batch APIs are an excellent option if the sequence and reference features aren’t needed to meet your common use cases.

Conclusions

In this post we have gone through definition of APIs, different type of APIs and differences between them.

This post was part of Topics

Back to home page

 

Leave a Reply

Your email address will not be published. Required fields are marked *