New to APIs? Then read this…

As the coronavirus continues to spread across the world, there is a surge in demand for grocery deliveries during this pandemic; lots of people either can’t get to the grocery store or aren’t willing to risk going out. This means grocery delivery apps are seeing record number of daily downloads. One of the biggest, most widely available grocery delivery services is Instacart that lets you shop from local grocery stores online. When you place an order in the Instacart website, the assigned personal shopper shops at major grocery stores in your area like Costco, Kroger or Walmart through their respective websites, picks up everything on your list and then delivers your order to you the same day.

Wondering… why did I just tell this?

Well, it is because just like any other application that we use on our mobile phone or on our computers, Instacart also uses an API (Application Programming Interface) which is dedicated to transfer data from various grocery stores’ database by communicating with their APIs’ and sends the aggregated information to the shopper to shop and deliver the items to you. In the entire process, Instacart application need not know the business logic underneath each grocery store’s API.

APIs are powerful tools for software engineers because it means that they don’t have to build every single component in their system from scratch. Imagine Instacart wants to add a new grocery store like Sprouts and has to redesign the entire application every single time! APIs avoid the same problem and software engineers can focus on the part of the software application that they view as their core competency.

An API is an intermediate software agent that allows dependent applications to communicate and exchange data efficiently with each other avoiding any user intervention. APIs provide a set of protocols, routines, and developer tools enabling software developers to extract and share information and let applications interact in an accessible manner. APIs allow the user or a company to customize the content and services which they use the most, deliver services and information more flexibly and also help anticipate software changes over time. An API also provides a layer of security which means the phone or the server each communicates with small packets of data, sharing only necessary information. The use of APIs has expanded over time.

Now that you have understood what an API is and what exactly it does, let’s take a look at the most common class of APIs that are available — the Web APIs. While at their core, APIs do perform similar functions, they can also differ from one another in some minor ways. A developer chooses among a variety of API protocols and standards depending on the purpose.

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) along with a definition of the structure of response messages, usually in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format.

REST (Representational State Transfer) APIs, also known as RESTful APIs that have an architectural style have grown in popularity of late. This means that there’s no official standard for RESTful web APIs. REST APIs are designed for developers to perform requests and receive responses based on Uniform Resource Identifiers (URIs) or Uniform Resource Locators (URLs) and HTTP protocol. REST APIs use JSON for data formatting which is considered to be browser-compatible, easy for humans to read and write and easy for machines to parse and generate. These APIs are extremely simple when it comes to building and scaling and also help facilitate client-server communications with ease.

REST APIs include four different HTTP commands: GET (Read), POST (Create), PUT (Update/Replace) and DELETE.

REST APIs:

  • Provide a simpler way to describe requests and responses
  • The data format, JSON being lighter and smaller makes it suitable for unreliable mobile networks.
  • Get much wider language support across different programming languages.
  • Easier to organize and manage data, content, and media when defined as simple RESTful resources.
  • Widely adopted because it is closely aligned with HTTP and is easier to pick up and use.

SOAP (Simple Object Access Protocol) APIs use a type of protocol which is a common communication protocol defined by a standard. SOAP is dependent on XML-based systems and programming, tending to have larger, more expensive data. These APIs also provide higher levels of security and better accuracy in the way messages are exchanged. SOAP provides an industrial-grade API solution that is suitable within most enterprise environments. Also, it makes it easier for apps running in different environments or written in different languages to share information. SOAP provides a solid, reliable pattern you can use when you don’t require a more date-centric, lightweight API design pattern like REST.

The SOAP building block describes what XML data is sent to the web service and client application. The following diagram represents the SOAP building block. It consists of:

SOAP Envelope: Defines the start and end of the SOAP message with the details of the SOAP message.

SOAP Header: Contains the credentials information such as authorization, authentication, etc. used during the processing of a SOAP message.

SOAP Body: Contains request and response information in the XML format defining the actual content of the message to be sent between the client and the webserver.

SOAP Fault: Displays an error message encountered during the transmission of a SOAP message and holds the status of SOAP messages and errors.

SOAP APIs:

  • Being a well-defined protocol is designed to handle industrial-grade APIs at scale.
  • Use the XML format that provides a treasure of parser, generators, and validation tooling that improve the quality of API messages.
  • Have rich tools available that help developers integrate and work with these APIs more easily.
  • More flexibility because these APIs can use HTTP, TCP, UDP, and SMTP as a transport.
  • Less desirable for mobile developers as these APIs use XML, which requires more bandwidth to transmit over networks
  • Can be viewed as a bulk enterprise solution, and not something we use as part of modern application development.
  • Fewer open source industry standards, with a more proprietary stance on interoperability.

As Applications these days are witnessing a dramatic rise to add more and more functionalities and build more applications, the dependence on APIs has also risen steeply. Whether you opt for SOAP or REST shouldn’t be a blanket decision, it should be project-based. As you evolve and expand your API strategy across your organization, you will be facing the debate between the both endlessly. SOAP and REST are two distinct design patterns that one should have in their API developer toolbox, so making sure you’re informed on both is important.

Some thoughts to ask yourself before choosing an API:

Who will be consuming your API?

What integrations and applications will it service?

What is the history of your organization and what developers are available on your teams?

Hope this was helpful!

Originally published at https://www.numpyninja.com on April 26, 2021.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store