I have worked in technology for a long time - 20 something years - and lately have heard about the need for best practices more than ever before and I want to put some definition around them and possibly incite discussion at the same time. The idea of the best practice as I hear it being tossed around is the absolute best way to use a technology or service. This gives me pause because every situation is completely different, even two individuals or organizations of the same size have different use cases for the applications they use.

Dictionary.com defines a best practice as:

A procedure or set of procedures that is preferred or considered standard within an organization or industry.

I like this definition because it is constrained by two things - an organization or industry. Because the use of the service or application depends on the need of the organization using the particular technology it needs to be separated from intent. The intent of how a service or technology is to be used is determined by the creator of the technology not by the consumer of the service.

Evolving from Intent

Azure has lots of services (likely an unknown number, as soon as I type a number that they could have - three new things might enter preview) these services are designed to meet the needs of Microsoft’s customers. To help its customers understand how to use the services in Azure, Microsoft creates Reference Architecture diagrams and lots of documentation. As a service gets into preview and out into the wild, customers might open issues about how the product works (or doesn’t) and create pull requests in the documentation to add or remove things that don’t work in practice (as well as intended or at all) to make things better and more useable for other customers of the same service.

A reference architecture shows how the service is intended to be used. It is high level and does not differentiate between any customer use case - If I am using an API Management Service to control access to APIs that run my printing services or create orders for pizza on the Internet (Dominos anyone?) the APIM is just a service I can use to accomplish this goal - Microsoft isn’t going to provide the detail of implementation for this service. They are going to help me understand the intent of the technology and what it is designed to help me achieve.

A general understand of how to implement this APIM technology comes from reference architecture and conversations with Microsoft around those documents.

The exact path to How

Because I am not running a trillion dollar software company, I as an individual or an organization have vastly different needs than Microsoft - I can use some of the same applications or services that they do to run my organization, but the implementation practices used to get there and the scale at which I use these services might be a bit different.

A vendor should provide information on the intent of a service - what is it that this service can help customers accomplish? In the case of APIM - creating a single endpoint for a set of APIs that perform tasks (likely an oversimplification). I put an APIM in place to provide a way for customers to interact with my organization. For example - if I am a pizza shop (and nerd out about technology) I could create an API for placing a pizza order and another for checking on the status of that order. I can then make this available to services like eatstreet or grubhub to leverage online ordering through their services. (Again - oversimplification) If I simply expose them to my customers:

order.mypizzashop.url for orders status.mypizzashop.url for status

The calls to these APIs are useful, but there might be things missing, like continuity and the expectation by developers that things might be in a similar space.

If I instead expose all of my APIs via one endpoint I can bring continuity for development and a single place to manage, store, access, and update any APIs I have now or in the future.

api.mypizzashop.url/order to place an order api.mypizzashop.url/status to check order status

This simplifies things quite a bit. That is, at least in part, the intent of an APIM. It does not dictate any type of best practice, simply that a service can help you to perform a set of actions. Some of that intent can act as a best practice, the fact that an APIM can bring documentation for your APIs to the surface and it is a good idea (a standard within the technology industry) to have documentation, lends it to be considered a best practice. I like the term standard there - because maybe mypizzashop does not write documentation or use documentation the same way as yourburgerjoint - maybe our organizations just both have documentation.

Semantics? Maybe - but expectations can muddy things

I am sure that this is semantics in some ways - is it a best practice or is it a standard? That is part of the problem - large technology companies produce applications and services to help their customers solve a problem - many of these companies have services that compete with other large technology companies to solve the same problem - this removes the product itself from being a standard.

Sticking with APIs for a moment - Microsoft has APIM and Google has Apigee. These two services are intended to solve the problem of managing, organizing, securing, and exposing APIs. They both accomplish that goal - but they likely have slightly different approaches - if I know how to use APIM from Microsoft I can probably (with some poking around) figure out Apigee. But the implementations are different.

The APIs that the services manage are a standard and the fact that many technologies use APIs to communicate is a standard - things operate the same way everywhere - but Apigee and APIM help to implement that standard.

The expectation of an organization that a provider of a service also provide the best possible way to implement the service is extremely misleading. I do not want Microsoft to tell me the exact way to configure APIM to ensure the best experience for mypizzashop.url customers. I want Microsoft (or Google) to explain to me the benefits of their service and show me generally how the service can be configured - help me understand how to get started. Then I want to work within my organization to determine the best way to leverage the technology. If my APIs are also used by services within my company - I should have less hurdles to clear to meet the same security standard as an external consumer of my services - there should be some trust (not much, but some) and things should work the same for both. Microsoft doesn’t know the ins and outs of online pizza ordering, they know the ins and outs of software and cloud management and service provisioning.

Each organization should evolve industry standards and reference architecture to their needs. Start with the What. The service and documentation to understand how it can help. Once that makes sense, work to understand how others within your industry are using certain technology - in many cases the vendor of the service can help with that - two pizza companies might be using APIM in a similar way.

Then work with your team to determine the best way to implement and adapt these technologies and standard to work best for your organization. Building specific and repeatable documentation along the way. Doing this will condense a technology standard to an industry standard within your industry, then further condense the ways of your industry to methods that work for your organization.

Once things are boiled down to a repeatable set of steps that work for your organization’s needs you have a best practice for using a set of technologies. This is not and should not be explicitly directed by the vendor of the solution - if that is how an organization expects to implement best practices, I would argue they are missing both parts of the concept - best and practice.

The only way to implement the best method for using a technology within an organization is to work within the organization by practicing the use of the technology or service to find what works and what doesn’t. Relying on the technology provider to know that for you just doesn’t work.

How does your organization interpret Best Practices? I’d be interested in seeing how others work with standards and best practices - leave a note in the comments.