Quantifying what an API does in simple, easy to articulate terms takes a lot of work. APIs are very technical, and often have a lot of moving parts, including paths, parameters, headers, and other elements that can evolve what an API does, something that can also shift the definition of what it delivers. Making APIs a very liquid concept to try and explain to humans, as well as to other systems and applications. One of the most important ways you can work to define what it is your API does is by establishing meaningful tags or API topics, which articulate the topical areas your API serves. Something that is reflected in the popularity of RESTful API design, and a more resource-centric way of defining what our APIs do.
Resources focus on what your API delivers.
Topics focus on how your API will be used for.
If your API is providing access to your blog, the API topic is “blog”. If your API is providing access to your press release, the API topic is “press”. These are some pretty easy, straightforward examples of defining topics that describe the functionality, but it is important to realize that all topics will not always be represented in the resource-oriented design of your API, and you will have to also consider the dimensions augmented by your API parameters, enumerated values, and other defining characteristics. The API resource might be “sensor”, but the API topic is defined by what is being measured by the sensor–something like water, weather, motion, etc. This is where an event-driven way of doing APIs will push us beyond just the design of our APIs, but shifting to consider how they will be used, and what are the meaningful events that will be occurring via an API once it is put to use by a client.
Resources focus on what your API delivers, but topics focus on how your API will be used for. Topics reflect the meaningful ways in which an API will be put to use, and for many API providers, how it is already being put to use. Many providers are just unaware of how their resources are actually being consumed, subscribed to, and being put to work. This is why the process of defining topics can be an important exercise for API providers, as it helps continue to push them out of their operational silo, talking about how people are using their resources, and brainstorming around the potential. RESTful API design has been valuable in pushing us to think more deeply about the digital resources we possess, and how we want to open up access to them. The recent event-driven evolution in the API sector is now pushing us to think more deeply about the meaningful events that are occurring across our API platforms, and which topics are the most relevant to consumers.
Topics define your APIs potential.
Topics define your API’s potential. There will be an overlap with your online marketing and evangelism efforts, and defining your API topics. API Topics can reflect the events that are already occurring via your platform, as well as the events you want to happen via your platform. The trick is always about striking a balance between what is happening, and what you want to happen. Letting the event-driven engagement with your APIs actually drive the conversation. Meaning the most active, most subscribed to, and most published to topics should rise to the top. Helping us move beyond where we only focus on API call volume, and only track how many calls are made to our APIs, to beginning to focus more on the topics people are genuinely interested in, publishing and subscribing to, and generating real-world value via our API-driven platforms.
Follow us on social