There is too much emphasis in the API sector on there being one way of doing APIs. Developers love to be religious about their tools -API tools included – and methodologies, but when it comes to finding success with APIs in the real world, it is rarely ever about any single approach. Yet, with each wave of new technology there are always people who like to shout out their window that their way of doing things is the right way, without ever realizing that they are shouting from a privileged position where they probably are only delivering newer API-driven systems, rather than supporting, evolving, or transitioning existing infrastructure.
While we’d all love to be always working with the latest technology, and have unlimited time resources to throw at our API projects, most of us have to make educated decisions about which API approach is the right one for the project we have in front of us. This is when having a complete view of the API landscape helps ensure you pick the right API tools for the job, and not ever limiting ourselves to any single API discipline, being able to work with, support, evolve, and develop APIs using any of the following API technologies:
– SOAP – Make sure you have the skills to be able to diagnose and connect to existing web services if you are working in enterprise environments.
– XML & JSON RPC – Whether it is Amazon, Slack, Flickr, or other 3rd party API, the chances you will need to work with an existing RPC APIs is still pretty high.
– REST – The place to start with all basic API projects, and the approach that will speak to the widest group of developers possible.
– Content Negotiation – Always consider allowing for the negotiation of CSV, XML, as well as JSON formats by default.
– Hypermedia – Also think about taking the experience to the next level by negotiating for a variety of hypermedia media types like HAL, JSON API, Siren, and others.
– API Query Languages – Know your resources, and your intended audience, and be able to include query language layers like GraphQL or Falcor when it makes sense.
– Webhooks – Make an API a two-way street by defining the first line of events that occur via an API, and push data and content to consumers when these events occur.
– Websub – Understand the benefits of implementing a complete, standardized publish and subscribe model when it applies.
– Server Sent Events (SSE) – Learn the benefits on one-way streams of data, using SSE to turn simple REST APIs into long running streams of information.
– Websockets – Be able to leverage two way streams of real time using websockets, being able to consume large volumes of data from platforms like Twitter.
– gRPC Using HTTP/2 – Understanding where the HTTP spec is headed, and paying attention to what companies like Google are doing when it come to gRPC and HTTP/2.
– Apache Kafka – Tuning into how companies are delivering high volume streams of data internally, moving around large volume of data, while also pushing relevant data to the last mile with other more lightweight approaches.
– Message Queuing Telemetry Transport (MQTT) – Know your network, and understand when a low-latency, lighter footprint protocol like MQTT might be more appropriate.
Depending on your project, you may need a different type of API to deliver what is expected. REST is always a good place to start, but maybe you have to work with an existing SOAP or XML RPC API. Depending on who your API consumers are, and what type of client will be doing the work, you might require a query language, or possibly be able to negotiate different API responses, resulting in different outcomes. You might also need to deliver real time streams of data in one direction, benefiting from the knowledge about push technology like Server-Sent Events (SSE), over using two-way streams delivered by Websockets. While REST is a great all purpose API technology, there are many other protocols, messaging formats, and approaches to help ensure a project is a success.
There is no single API approach to rule them all. Know your API technology. Tune into how different API leaders are getting their work done. Don’t listen to API pundits who profess their way is the best way. Understand the pros and cons of each approach to delivering APIs, and ensure you will be confident in picking the right API tools for the job when you need to. APIs are a pretty wide term to describe how we deliver programmatic interfaces for use in a growing number of applications. Don’t limit your options by being dogmatic with your API tools, and make sure you always leave your options open, ensuring you always have the right tool for the job.