What is an API?
An API, or Application Programming Interface, is a set of rules that define how applications can communicate with each other. A client makes an HTTP request to an API at an endpoint which it has access to. The API validates the request and passes the request to the destination server or program. The server sends a response back, first through the API, which then transfers it back to the client. The API provides security by decoupling the consuming application from the infrastructure providing the service. Once an API service and a client exchange authentication keys, they communicate through the API, meaning they don't have full access to each other, but enough information can be passed securely to get work done.
A client can issue certain kinds of HTTP protocol requests (or HTTP "verbs"), of which there are four main types:
- GET - This request reads information from a record in the database.
- PUT- This request changes a record's information in the database.
- POST - This request creates a new record in the database.
- DELETE - This request removes a record from the database.
Technically, the above describes web API usage, which is another reason APIs and web services get mixed up. APIs can exist outside of the web, however, and have since computers were first connected together. The important distinction is that APIs are used to link applications, and while today that is usually done via HTTP or HTTPS, it wasn't always this way.
What are web services?
According to the W3C, 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.
Web services use SOAP and XML to allow communication across different programming languages and different applications across HTTP. A SOAP message is just XML sent between client and server. This was an open source solution (see Apache Axis for XML-RPC, for example), to a problem in the early days of the Internet of exchanging data and messaging between newly connected systems.
Each SOAP document needs to have a root element known as the <Envelope> element, the first element in an XML document. The envelope element contains the header and the message body. The header contains the routing data which tells the XML document to which client it needs to be sent to, while the body will contain the message. But how does the client know where the web service lives?
Web Services Description Language (WSDL)
The Web Services Description Language, or WSDL is an XML document that tells a client where the web service lives and what it does. The WSDL is a pretty verbose XML document, describing every SOAP interaction it will accept, so it is generated automatically when a new web service is built to save time. A client who wants to view the WSDL of a web service sends a request like this: `http://webservice.example:1234/foo?WSDL` to get that web service's WSDL file. This assumes the web service is set up to deliver its WSDL. But wait- we still don't know where to find this web service in the first place! For that, we use a SOAP message to call UDDI.
UDDI
The Universal Description, Discovery and Integration (UDDI) is an XML-based registry by which businesses worldwide can list themselves on the Internet, and a mechanism to register and locate web service applications. UDDI enables businesses to publish service listings and discover each other, and to define how the services or software applications interact over the Internet. It is designed to be called by SOAP messages and to provide access to WSDL documents for web services. UDDI is kind of like an old-school API directory, listing addresses and capabilities for web services.
API vs web services
Every web service is an API "since it exposes an application's data and/or functionality” but not every API is a web service. APIs are just the terminals that enable client-server relationships, while web services are an architectural style for integrating Web-based applications using the XML, SOAP, and WSDL open standards over an Internet Protocol backbone. XML is the data format used to contain the data and provide metadata around it, SOAP is used to transfer the data, and WSDL is used for describing the services available. You can probably see why APIs and web services get confused- they have a lot to do with each other, and nothing to do with each other. Web services even offer different types of web services (SOAP and REST). You can probably also see why REST APIs took off and SOAP floundered- REST harnessed the power of APIs by bypassing the SOAP/XML/WSDL/UDDI headache entirely. This isn't to say web services don't still have their uses (AJAX is a very popular use), or that REST is perfect (see GraphQL), but the similarities and differences below tell the story of a tool waiting to be freed from restrictions.
- Web services require SOAP and XML to transfer data over a network, while APIs can use any protocols or design patterns.
- APIs allow applications to communicate, while web services allow machines to communicate.
- Web Services requires a network connection while APIs may or may not require a network for their operability.
- Web services require SOAP and XML, which are no longer the most popular standard.
- APIs are more efficient, with RESTful web services offering a more light-weight architecture web services are heavy.
- Web services only support HTTP as a backbone, while APIs are more flexible.
Conclusion
The confusion between web services and API stems a lot from nomenclature confusion. For example, we have Amazon Web Services, or AWS, providing elastic cloud computing. (For a fun article about the old days, check out this article about AWS offering SOAP and REST APIs in 2004). We have SOAP and REST APIs, which use the same interface, but in radically different ways. We hope this article helped in your understanding.
