Is My Web Service an API?

27 Jan 2016
by: Lou Powell

There are lots of people questioning the difference between a web service and an API. Isn't an API just a web service being packaged as this new wonder solution for integration; when in reality, we have been building these for over 15 years? Well the short answer is no. An API is not just a web service.

Ask these questions to determine if your web service is an API:

1) Is my web service used by more than one application?

APIs are intended for broad use.

2) Can my web service be procured through self-service?

APIs should be accessible through a website/app for rapid procurement. The service should be well documented to allow developers to consume it with little to no human interaction. APIs support speed and convenience of use.

3) Is my web service designed for broad consumption?

APIs are designed to provide specific functionality to a broad group of developers. If your web service was created for such a unique use case that you have trouble envisioning how it could be used by other applications to serve the same purposes, it may be too narrowly scoped to be an API.

4) Are the data elements and attributes used in my web service plain English and understandable without mapping or explanation?

APIs are intended for use by developers who do not have explicit knowledge of your business systems. It is important that the vocabulary you use is plain, common, and understandable.

5) Is my web service developed to be consistent with our other web services?

APIs are a consistent product in areas like authentication, error handling, language, and parameter/object structure. A good set of APIs are coordinated in all these areas even as they cross or source from different LOBs or business systems.

6) Does my web service provide meaningful error messages that inform developers of what was expected?

APIs are intended to be consumed with little to no interaction with a technical team. Everything they need to know to be successful in utilizing the API should be inherent in the design or available in the documentation and through meaningful error messages. Make sure your error messages are explicit and provide cause and resolution.

7) Was my web service designed to be platform/stack agnostic?

APIs should be provided in formats and protocols that can be consumed equally well regardless of what platform or language the consumer is developing on. This may mean exposing endpoints that allow for multiple formats (SOAP, ReST, JSON, etc.)

8) Is my web service agile?

In regards to unanticipated use, an API should be agile in responding to the changing needs of the user base. If an API does not meet the needs of the user community, it will cease to be used. Remember, consumption is the ultimate measure of success for an API.

9) Will my web service elastically scale?

APIs are written to provide valuable access to data for unknown use. An API should be capable of scaling to meet the demand of rapid or even viral consumption.

10) Is my web service fast?

Time to Interaction (TTI) for the consuming applications is a critical factor in user adoption of technologies and API performance is critical to fast TTI. How fast? As fast as you can possibly make it.

If you answered yes to all of these questions, then your web service is an API. If you answered no to any of the questions, then you may have a little work to do before your web service will truly be a business class API.