Consistency is perhaps one of the most critical facets of any developed product. That the product performs well, uses the same interaction points for predictable functions, and align its development goals, are key for success and longevity in the API space. No matter how large or small an API is, good development never goes out of style.

In our previous piece, we discussed four general areas of consistency: Naming and Endpoint Consistency, API Design Paradigm, Error Handling, and Documentation. While these are undoubtedly important points, there are even more considerations when looking to provide a universally consistent API experience.

Below, we discuss five more areas of consistency for your API designs. These concepts generally apply regardless of what kind of API you develop and what service you provide.

1. Support and Feedback

Have a clear channel for support and accepting developer feedback, and encourage its use

Ultimately, the API provider is separated from the developer user. The developer consumes the API however they choose to implement it, while the provider can only assume the average use case based on analytics and usage patterns. To prevent this, support processes and feedback channels are vital.

Support can take a few forms. For some APIs, live support is very helpful. These APIs often fall within the services industry — eCommerce support systems, troubleshooting ticket systems, etc. Ongoing support not only forms the best support for the average user; it can also inform developers as to the current status of the API, consistently appearing problem areas, and unmet needs of the consumer.

Other APIs may suffer from this type of live support. Evergreen APIs that serve a single particular function, such as an API that serves local time data, may necessarily be limited to just that function. After all, if an API only serves time, it doesn’t really matter whether a consumer wants a timer function, a scheduling function, etc. — that’s not what the API is for. That said, there may be cases where the API is serving erroneous data, not syncing properly to certain devices, or simply not working. In such cases, asynchronous support such as error reporting contact forms, error reporting endpoints, etc., can serve a vital function.

With all of this said, no mode of support or feedback lives past the first loss of consistency. When looking at the sum total of avenues for communication, a user can quickly fall down a black hole — a ticket submitted here, an email sent there, all dependent upon the developers routinely utilizing this data and using the systems on offer. If a developer notes that a system of feedback is available, it’s functionally useless if the developer then does not proceed to use that system. Too often has a provider created a mailbox with an email like “feedback@coolapi.com” only to never check the feedback for the rest of the API lifecycle.

This is especially important when noting that there are many types of support and feedback mechanisms. Suppose an API has a public function as well as internal endpoints. In that case, it may be the correct choice to have different support and feedback apparatus choices depending on who the targeted audience is. In such situations, accuracy and consistency are even more important.

Finally, the mode of communication is only as consistent as the focus and approach. Especially at the enterprise level, communication is essentially a form of public relations. As such, all who engage in communication channels should have at least some sort of training, understanding, or skill set around providing support. A consistent user experience backed by a trained professional familiar with the core product will promote an excellent developer experience. A failure in consistency isn’t going to reflect on the singular poor experience but the support platform.

Ultimately, what is important here is that some channel is provided, and that the channel is clearly demarcated, made available, and utilized in core development.

2. Change and Versioning

Establish consistent versioning and deprecation procedures

Perhaps the most crucial area to ensure consistency is within your API’s various technical aspects — this includes how you evolve your service. Versioning is a change management method that seeks to ensure that critical deployments, interaction and usage shifts, and altered paradigms are effectively distributed and implemented to all users.

Versioning should be consistent and communicated properly. Ineffective versioning can be extremely harmful to the average API and its consumers. We’ve discussed this at length before, and we suggest reading through our collected thoughts concerning API versioning best practices and change communication.

Second, having a consistent methodology behind sunsetting and deprecating APIs and API versions is incredibly important. We’ve also discussed this before, summarizing the core problem as thus:

“Deprecation and sunsetting terms are some of the most important policies to communicate to developers. Your communication here will not only secure your current API, but if you’re migrating to something else, will likely ensure its success as well – users only trust providers who communicate. Effective, smart sunsetting and deprecation isn’t just good for your code, it’s good for your users, the API space, and the industry at large.”

3. Security

Adopt a consistent internal security practice

Security is another area where consistency is incredibly important. Having consistent endpoints with consistent security standards and baseline monitoring and response methods is incredibly important. Every small failure of consistency here can compound and open more vulnerabilities that you may not even know exist.

One common security issue is allowing different access points for different user classes. While this most often happens within the context of an exposed “test server,” this can also happen with test endpoints for new functions. When those endpoints are created and left open once their usefulness has expired, this only creates a risk of ingress.

Additionally, any security choice made throughout the API should apply to the API in totality. Things like rate limiting are great to prevent denial of service attacks, but if those limits don’t apply to elevated credentials, then you’re creating a massive flaw in your security. In such a system, the second an elevated credential is usable by a threat actor, you’ve made a situation where your massive security solution does not exist for the direct threat actor.

Ultimately, security is not a single fix. “Security” in an API is not like locking a single door and calling yourselves secure — instead, it’s like inspecting a two-mile-long castle wall for weaknesses, erosions, or high points that can be traversed. It’s an active process of inspecting for weakness, however minor, and then addressing those weaknesses to balance the user experience with restricted access.

4. Authentication and Authorization

Ensure API keys are dealt with responsibly, and promote a consistent handling behavior

One major consistency issue is in the processing of user authorization and authentication. While this specific area of concern covers a handful of domains, we’ll more specifically discuss a few general types here.

Firstly, the use of API keys and the storage of those keys should be consistent both in process and location. API keys can be extremely powerful, and without a proper strategy, they could be inadvertently exposed, given far too much power, or even used for entirely incorrect purposes. Keys should be provisioned based upon a consistent set of standards, and they should only be made for access to a limited set of resources for a specific purpose. There should be no “skeleton key.” Most importantly, these keys should have a consistent revocation and expiration system to ensure that no key lasts forever, and that keys can be adequately cycled and distributed.

Secondly, when any account is closed or terminated, you must properly handle the associated credentials within a set expiration process. Improper expiration of certificates is a significant source of ingress into systems from unauthorized users, as they, when paired with poor API key handling, can leave valuable sources of interaction completely open. Add on to this the fact that these credentials are often overlooked as sources of insecurity (given that they were, at one time, trusted), and you’ve got a perfect storm resulting in a threat actor flying “below the radar”.

5. Platform Consistency

Spec-driven development can ensure documentation reflects production environments

One final point of consistency is the unification of the API experience from the perspective of documentation and specification. When developing an API, unless the specification is used to create the documentation outright, there is a possibility that the output is going to differ from the input. While this is typically minor and can be fixed by an attentive developer, the reality is that these differences often propagate through multiple versions, resulting in documentation that must go through an overhaul to be even remotely usable and valuable.

It’s also possible that if the specification is used to create the output API, but this process is done at the start of a series of developments, that the end output will still be mismatched. The worst part of this scenario is that the output is different without apparent cause; it is more likely that this scenario plays out without it being obvious to the developers than the former scenario.

At all times, developers should strive to ensure that their public docs and statements in specification match the actual deployed instances and that the ethos and processes are reflected adequately. This includes ensuring that the numerous diverse outputs which inform the user match the inputs, but it also includes matching the stated goal and purpose of the API are reflected in the actual functions. It’s not ok for an API to state that its purpose is to do something, and once the user enters the API, it’s unclear exactly how (or even if) it does this – that is the worst possible scenario for user experience.

Be Consistent

These points are still are only part of the consistency toolkit that developers should apply. It’s important to remember that no list will ever be a complete guide to consistency because consistency is not an end state — consistency is much more a way of thinking, a mindset that applies throughout the development process. To be consistent is not to meet every single possible permutation and situation — instead, to be consistent is to do your level best to approach every known, conceivable issue of consistency in your API.

Nevertheless, when dealt with on the whole, these points should provide a solid starting point for any API. Proper integration and more direct proper addressing of inconsistency will result in a better, more effective, and more consistent experience for the end-user and developers integrating the API.

What do you think about our areas of consistency? Are there any major points that we’re missing? Let us know below!