7 Big rules for microservices to build persistent APIs

In recent years, the rapid development of micro-service architecture, Sparkpost is one of the early landing micro-service architecture companies, they found that the ground-floor micro-service process, not only need to consider service discovery, service registration, service call tracking chain and other architectural issues, but also need to pay attention to the micro-service API change management. One of the major features of MicroServices is the independent release and rapid iteration, but the premise is stable enough that they encounter many problems in the process of building APIs using microservices:

2. Customers (micro-service consumers) often feedback API upgrade changes are not available, and sometimes the scope is not controllable, resulting in the micro-service extension, or even online failure, contrary to the micro-service original intention.

4. Changes in API parameters or return results result in inconsistent client behavior, a heavy reliance on client refactoring, and the team's inability to focus on innovative work.

6. API is not easy to use, the user technology stack is not unified, each API abstraction and encapsulation, error-prone.

8. The lack of documentation and the use of booting requires a lot of support work.

10. Behind closed doors, the output of micro-services often can not meet demand, running for a period of time will be gradually discarded.

After years of exploration and practice, Sparkpost has summed up a number of best practices to guide them in building a persistent and stable microservices API. Today, their APIs are used by tens of thousands of customers, including Pinterest, Zillow, and Intercomto, sending more than 15 billion emails per month.

In this article, I'll review a few choices and best practices.

RESTFUL is the best, but to be practical, there is no need for scholarly

First and foremost, the step we take is to decide to use REST as an API. Our philosophy is to choose the following three elements as the basis for our API:

1.HTTP: This includes response codes and operators. Operators include POST, GET, PUT, and delete, which can be mapped to basic CRUD (create, read, update, delete) operations.

2.EESOURCES: These are entities that are executed by the HTTP operator.

3.JSON (JavaScript object notation): This is a common format for data interchange.

These three elements provide everything you need for a practical REST API, including simplicity, portability, interoperability, and modification. Once the APIs are built, users can easily integrate them regardless of their programming language, including C #, PHP, and NODE. JS, JAVA, and even CURL in the SHELL. They don't have to worry about potential technological developments, including a variety of microservices.

When we created the Sparkpost API, we tried not to use purely restful models too much, but to choose ease of use. Here are two examples that might not follow RESTFUL best practices:

1.get/api/v1/account?include=usage

2.post/api/v1/sending-domains/example.domain.com/verify

The first example uses a query string parameter to filter what is returned in the entity. In the second example, we use the verb "VERIFY" in the terminal name, which may not be RESTFUL. We will discuss each new use case and try our best to ensure its consistency and ease of use.

Evolve and manage Change

We have many developers and teams in the use of our API's microservices and are constantly changing. When the engineer determines that it has passed our tests, we automatically deploy the changes to production.

We decided early on to let our API be consistent in terms of usage practices and how to manage changes. We have established a governance team that includes engineers representing each team, members of the Product management group, and CTO. This group establishes and enforces the API conventions that we adhere to and is fully documented.

The documented conventions allow us to reduce inconsistencies and make it easier to define each new endpoint. Here are some of the conventions we've established:

• url query parameters and JSON fields are also lowercase underscores, and are case-sensitive.

• non-expected query parameters and JSON fields in the request body should be ignored.

• A new API resource, endpoint, or operation on an existing resource.

• A new optional parameter or JSON field.

• The new field that is returned in the JSON response body.

Conversely, a disruptive change includes anything that could disrupt user integration, such as:

• Change the data type of the field.

• A new required parameter or JSON field.

• Delete an existing endpoint or request method.

• Substantive behavior differences for existing resource methods, such as changing the default value of an option to "TRUE"

do not make any changes when you do not create damage

Even if they are fixed bugs or inconsistent results, you should avoid changes. Typically running in this particular case is more risky than destroying the integration with the client. If the changes are diverse, we will be very cautious and look for other ways to achieve our goals. This can sometimes be done by simply allowing the user to change their behavior through account settings or API parameters.

However, there is always a situation that introduces changes to the interests of our users over any potential adverse factors that will be introduced. But in these cases, we followed these best practices:

• We analyzed the API logs to see how many users the changes might affect.

• We give users an advance warning for at least 30-60 days.

• We sent an e-mail or published a blog post that contained detailed information about the changes and why we had to make those changes.

• We provide upgrade guidance in the API documentation.

"One version" rule

In the last three years, we've made thousands of modifications to the API and it's still the first version. We decided early on not to exceed the first version of the API, because doing so would add unnecessary complexity, slowing down the user's use of our newest and most powerful features. Versioning of APIs also slows development and testing, complicates monitoring, and makes user documentation confusing.

• Put this version in the URL: easy to do, but from a semantic point of view it is a bad choice because the entity has no change between V1 and v2.

• Add a custom caption: It's also easy to do, but not semantically strong.

• Place this version in the ACCEPT header: semantically strong but the most complex method.

using the client library to help non-JAVASCRIPT users

Some of our users prefer PYTHON, C #, JAVA, or PHP rather than JAVASCRIPT. We integrate the API into the application by maintaining the client library, which provides an easy-to-use library for its code, to quickly integrate it.

Over time, our customer base has changed and we have made the appropriate version. We have learned that abstraction is difficult when packaging an ever-growing API, so we focus on providing a thin layer of abstraction and using some syntax shortcuts to simplify the use of our APIs. This allows our users to quickly access any of our APIs and has a lot of flexibility

"Document-first" policy

We treat our document as code and use it to record our API changes before writing or changing an API code line. Doing so helps us to implement our engagement, keep everything consistent, and maintain a good customer experience. It also cuts back on support costs.

We maintain our documentation on GITHUB, which makes it easy for technical and non-technical users to make changes. We also found it easier to review the way changes are made. We use the API Blueprint Markdown format and Jekyll to generate HTML documents, as well as a powerful search service called Algolia. This allows us to provide a better customer experience, including mobile devices.

For those who do not want to "roll up their own" documents, we recommend OPENAPI (formerly known as "Swagger"), apiary, and API Blueprint. It is important to avoid using tools that are not appropriate for REST API documentation. We recommend that you include a bright orange "run in POSTMAN" button in your document, which makes it easy to try out an API, as well as examples of success and failure scenarios.

listen to the user's comments

Finally, we recommend that all developers pay attention to their users ' feedback. Sparkpost has a community Slack channel, and thousands of users can easily contact our product, support, engineering and executive management team members. We also have a dedicated team of developer relationships who focus on partnering with the developer community. All of this allows us to better listen to our users and integrate their feedback into our API.

Summary

With the development of micro-service architecture, the rapid growth of micro-services, some enterprises within the operation of more than 1000 micro-services, and is still growing, each micro-service contains dozens of APIs, how to manage the change of the MicroServices API will become the focus of the enterprise, Sparkpost according to these rules and best practices, Provide a solid foundation for their business from providing on-site e-mail infrastructure to fully cloud-based e-mail delivery services.

7 Big rules for microservices to build persistent APIs