Shulou(Shulou.com)06/02 Report--

This article introduces what are the seven rules for microservices to build a lasting API. The content is very detailed. Interested friends can use it for reference. I hope it will be helpful to you.

Foreword

In recent years, micro-service architecture has developed rapidly. SparkPost is one of the early landing micro-service architecture companies. They found that in the process of landing micro-services, they 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 change management of micro-service API. One of the major features of microservices is independent release and fast iteration, but only if they are stable enough that they encounter a lot of problems in the process of using microservices to build API:

1. Customers (micro-service users) often report that API is unavailable after upgrade changes, and sometimes the scope of influence is out of control, resulting in delays or even online failures of the micro-service, which goes against the original intention of micro-service.

2. The client behavior is inconsistent due to the change of API parameters or the return result. Depending on the client needs a lot of refactoring, and the team cannot focus on innovative work.

3. API is not easy to use, the user's technology stack is not unified, and it is easy to make mistakes when abstracting and encapsulating API respectively.

4. Lack of documentation and user guidance, requiring a lot of support work

5. Working behind closed doors, the output of micro-services often can not meet the demand, and will be gradually abandoned after a period of time.

After years of exploration and practice, SparkPost has summed up a large number of best practices and guided them to build a lasting and stable micro-service API. Today, their API is used by thousands of customers, including Pinterest, Zillow and Intercomto, sending more than 15 billion emails a month.

Principle 1. Restful is the best, but to be practical, there is no need for pedantry.

The first and most important step we took was to decide to use REST as the API. Our philosophy is to choose the following three elements as the basis of our API:.

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

2. Resources: these are the entities executed by the HTTP operator.

3. JSON (JavaScript object representation): this is a general data exchange format.

These three elements provide everything you need for a practical REST API, including simplicity, portability, interoperability, and modifiability. After building API, users can easily integrate it, regardless of their programming languages, including C #, PHP, and Node. Js, Java, and even CURL in Shell. They don't have to worry about potential technological developments, including a variety of micro-services.

When we created SparkPost API, we tried not to use the pure REST model too pedantic, but to be easy to use. Here are two examples that may 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 the 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 conform to Restful. We will discuss each new use case and try to make sure it is consistent and easy to use.

II. Development, evolution and management of change

We have many developers and teams using our API microservices and are constantly changing. When the engineer determines that it has passed our test, we will automatically deploy the changes to production.

We decided early on to keep our API consistent in terms of usage conventions and how to manage changes. We set up a governance team that includes engineers representing each team, members of the product management team, and CTO. This group establishes and enforces API conventions that we follow, and is fully documented.

Documented conventions allow us to reduce inconsistencies and make it easier to define each new endpoint. Here are some of the conventions we have established:

When naming words, the URL path is a lowercase letter with a hyphen and is case sensitive.

URL query parameters and JSON fields are also underlined in lowercase and are case sensitive.

Unexpected query parameters and JSON fields in the request body should be ignored.

The governance group also sets basic rules for how to make changes and what types of changes are allowed. There are some good API changes that are beneficial to users and do not break their integration, including:

An operation on a new API resource, endpoint, or existing resource.

A new optional parameter or JSON field.

The new field returned in the JSON response body.

Instead, a disruptive change includes anything that could break 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.

Substantial differences in the behavior of existing resource methods, such as changing the default value of options to "true"

Third, do not cause damage when making any changes

Even if they are the result of fixing bug or inconsistencies, modifications should be avoided. It is usually more risky to run in this particular case than to break integration with the client. If the changes are diverse, we will be very careful and look for other ways to achieve our goals. Sometimes this can be done by simply allowing users to change their behavior through account settings or API parameters.

However, there will always be a situation in which changes are introduced to the benefit of our users more than any potential disadvantages that will be introduced. But in these cases, we follow these best practices:

We analyzed the API log to see how many users the change might affect.

We give users at least 30 to 60 days' advance warning.

We sent an email or published a blog post containing detailed information about the changes and why we made them.

We provide upgrade guidance in the API documentation.

IV. "one version" rule

We have made thousands of changes to API in the past three years, and it is still the first version. We decided early on not to exceed the first version of API because doing so would add unnecessary complexity and slow down users' use of our latest and most powerful features. Version control of API also slows development and testing, complicates monitoring and confuses user documentation.

In addition, there is no version control for our API, which means we can avoid arguments around the topic. There are three ways to implement a version of API, all of which have potential drawbacks:

Put this version in URL: it's easy to do, but it's a bad choice from a semantic point of view, because the entity doesn't change between v1 and v2.

Add a custom title: it's also easy to do, but not semantically strong.

Place this version in the accept header: the semantic but most complex approach.

Use client libraries to help non-javascript users

Some of our users prefer Python, c #, Java or PHP to JavaScript. We integrate API into our applications quickly by maintaining client libraries that provide easy-to-use libraries for their code.

With the passage of time, our customer base has changed, and we have made a corresponding version. We have learned that abstraction is difficult when wrapping a growing API, so we focus on providing a thin layer of abstraction and use some syntax shortcuts to simplify our use of API. This gives our users quick access to any of our API and has a lot of flexibility

VI. The strategy of "document first"

We treat our documentation as code and use it to record our API changes before writing or changing a line of API code. Doing so can help us implement our agreement, keep everything consistent, and maintain a good customer experience. It has also cut support costs.

We maintain our documentation in GitHub, which makes it easy for technical and non-technical users to make changes. We also found it easier to review the way changes were made. We use 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 "scroll upgrade their own" documents, we recommend OpenAPI (formerly known as "Swagger"), Apiary, and API Blueprint. It is important to avoid using tools that are not suitable for REST API documents. We recommend that you include a bright orange "run in Postman" button in the document so that you can easily try out an API, as well as examples of success and failure scenarios.

7. Listen to the opinions of users

Finally, we recommend that all developers pay attention to the feedback from their users. SparkPost has a community Slack channel where thousands of users can easily contact members of our product, support, engineering and executive management teams. We also have a dedicated developer relations team that focuses on working with the developer community. All of this allows us to better listen to our users and integrate their feedback into our API.

With the development of micro-service architecture, micro-services are growing rapidly. Some enterprises operate and maintain more than 1000 micro-services, and they are still growing. Each micro-service contains dozens of API. How to continuously manage micro-service API changes will become the focus of enterprises. According to these rules and best practices, SparkPost It provides a solid foundation for their business from providing on-site email infrastructure to sending email services based entirely on cloud computing.

This is the end of the seven rules for building a lasting API for micro-services. I hope the above can be helpful to you and learn more. If you think the article is good, you can share it for more people to see.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.