Sun May 22, 2022

The Developer’s Guide to Web Service APIs, Structures, and Protocols

interfaces

Each time you log in to your favorite website using your Google account, the website communicates with Google via a web API.

Before delving into what web service APIs are, perhaps I should define what an API is. An API is a component that enables communication between two systems or applications.

Web service APIs are APIs that depend on a network to enable communication between two systems. The World Wide Web Consortium (W3C) defined web services thus:

“A web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the web service in a manner prescribed by its description using SOAP-messages, typically conveyed using HTTP with an XML serialization in conjunction with other web-related standards”.

Developers interact with web services on a daily basis. This is why an in-depth understanding of these important components is necessary. I cover the differences and similarities between APIs and web services in another article.

What Are the Types of Web Services?

There are 4 main types of web service APIs, namely:

XML-RPC (Extensible Markup Language-Remote Procedure Call): This is the most basic XML protocol. This protocol allows data exchange between a variety of devices on a given network. It facilitates the transfer of data and other information between clients and servers using HTTP.

REST: REST is an acronym for Representational State Transfer. REST services use HTTP and support a range of HTTP methods such as GET, POST, PUT, and DELETE. It allows for communication and connectivity between API-based devices and the internet.

SOAP: SOAP stands for Simple Object Access Protocol. A Web service protocol that uses XML to facilitate transferring data and documents over HTTP or SMTP (Simple Mail Transfer Protocol). It uses XML to enable communication between independent processes running on different platforms.

UDDI: an abbreviation for Universal Description, Discovery, and Integration, is an XML-based standard for detailing, publishing, and discovering web services.

Other web services that use markup language

  • JSON-RPC.
  • JSON-WSP
  • Representational state transfer (REST) versus remote procedure call (RPC)
  • Web Services Conversation Language (WSCL)
  • Web Services Description Language (WSDL), developed by the W3C
  • Web Services Flow Language (WSFL), superseded by BPEL
  • Web template
  • WS-MetadataExchange
  • XML Interface for Network Services (XINS), provides a POX-style web service specification format

Key Features of Web Services

Interoperability: One of the major benefits of web service is interoperability. Web services provide a standardized way of integrating web-based applications using the XML, SOAP, WSDL, and UDDI open standards over an Internet Protocol backbone applications to communicate, exchange data, and share services among themselves.

The common standards-based communications methods have been developed and these make it possible for web services to be platform-independent.

Usability: Web services are designed to be used for a web page request and to receive data. Web services are the same. The capability of web services varies from simple information lookup to complex algorithmic computations.

XML is the data format used to contain the data and provide metadata around it, SOAP is used to transfer the data, WSDL is used for describing the services available, and UDDI lists what services are available.

Reusability: Web Services are designed to be combined to deliver more value-added services. As building blocks for other services, web services make it easy to reuse web service components. Additionally, legacy applications can be wrapped into web services so that they can be used by others.

A web service is deployed over the internet using standard Apache, Axis2 to generate HTTP and WSDL documents. Deployment is easy due to this.

Cost: The cost of operating web services is reduced because new systems are assembled from packaged web services. The saved cost can be a benefit to both the solution provider and the customer. Furthermore, efficiency is achieved at the same time.

How Does SOAP Work?

Data transmitted over the internet has to be structured in some way. The two most popular data formats are XML and JSON.

XML (or Extensible Markup Language) is the text format that SOAP uses. It establishes a set of rules to structure messages as both human and machine-readable records. Albeit, XML is quite verbose as it aims to create a web document with all its formality.

The Message Structure of SOAP

Standard SOAP requests appear as an enveloped messages consisiting of four elemetns, each with their unique funveloped message consisting of four unique parts, each with its own function.

Envelope: the core and essential component of every message. It starts and concludes messages with its tags, enveloping them, hence the name.

Header: an optional element that determines the specifics, and extra requirements for the message, e.g. authentication.

Body: includes the request or response.

Fault: another optional element that shows all data about any errors that could emerge throughout the API request and response.

Soap image

How Does REST Work?

Here’s an example. Let’s say a call is made from a client to a server, and data is received back over the HTTP protocol. Facebook’s Graph API is an easy way to show the similarities between a REST API call and the loading of a webpage. Say someone wanted to pull up the Facebook page for YouTube, for example. That person would enter in the URL as normal, www.facebook.com/youtube.

If that person were a developer, instead of “www,” they would enter “graph.facebook.com/youtube” and would receive a response to the API request that was made through their browser.

The result of the request would show structured data, organized according to key-value parameters. Extending this example, that structured data would include how many likes the page had, how many accounts were following the page, etc.

Structure of a REST Request

The Endpoint: This is a unique URL that represents an object or group of objects of data. Each API request has its own endpoint, which is what the HTTP client is directed at in order to interact with data resources.

The Method: HTTP methods (which will be explained in further detail below) are an integral part of a RESTful API request. These methods – GET, POST, PUSH, PATCH, and DELETE – correspond to create, read, update, and delete resources.

The Headers: REST headers contain information that represents metadata associated with every single REST API request. A REST header indicates the format of the request and response. This provides information about the status of the request.

The Data: A REST API request also consists of data (also referred to as a “body”) that usually works with the POST, PUT, and PATCH HTTP commands and contains the information and representation of the resource that will be created.

Major Differences Between SOAP and REST

SOAP is a strict protocol. REST is an architectural pattern
SOAP can’t use REST because it is a protocol REST can use SOAP web services because it is a concept and can use any protocol like HTTP, SOAP.
SOAP only permits XML REST permits many different data formats including plain text, HTML, XML, and JSON
SOAP requires more bandwidth and more resources REST requires less bandwidth and fewer resources.
SOAP supports both SMTP and HTTP protocols REST requires the use of HTTP only
SOAP is more reliable than REST REST is less secure than SOAP.
SOAP is faster than REST Great for building a service with multiple, non-CRUD methods

Conclusion

There are many use cases for web services and the use case is largely defined by the team working with them. Other factors like speed, team size, and project specifications help inform what web services to use.

Ultimately, the information I’ve provided here should help you make a good choice of web service for your project.

APIToolkit logo

Copyright APIToolkit.io ([email protected])