Service Design
When building a service, we want to ensure our service does not become coupled to another team’s service, requiring a coordinated release. We want to maintain our independence. We also want to ensure we are not breaking our consumer when deploying updates, including breaking changes. To achieve this, we will need to carefully design the interfaces, tests, and versioning strategies, and document our services while we do so.
When defining the interfaces, we need to ensure we are not exposing unnecessary information in the model or internals of the services. We cannot make any assumptions of how the data being returned is used, and removing a property or changing the name of an internal property that is inadvertently exposed in the API can break a consumer. We need to be careful not to expose more than what is needed. It’s easier to add to the model that’s returned than it is to remove or change what is returned.
Integration tests can be used when releasing an update to identify any potential breaking changes. One of the challenges with testing our services is that we might not be able to test with the actual versions that will be used in production. Consumers of our service are constantly evolving their services, and we can have dependencies on services that have dependencies on others. We can use consumer-driven contracts, mocks, and stubs for testing consumer services and service dependencies. This topic is covered in Chapter 6, “DevOps and Continuous Delivery.”
There will come a time when we need to introduce breaking changes to the consumer and when we do this, having a versioning strategy in place across the services will be important.
A Common Versioning Approach
A common versioning strategy across all services would be recommended. Service owners have a lot of technology freedoms, but agreeing to a common versioning strategy as well as a common logging format will ease management and service consumption across the organization.
There are a number of different approaches to versioning services. We could put a version in the header, query string, or simply run multiple versions of our service in parallel. If we are deploying multiple versions in parallel, be aware of the fact that this will involve maintaining two branches. A high-priority security update might need to be applied to multiple versions of a service. The Microsoft Patterns & Practices team has provided some fantastic guidance and best practices for general API design and versioning here: https://azure.microsoft.com/en-us/documentation/articles/best-practices-api-design/.
It’s also important that the services are documented. This will not only help services get started consuming the API quickly, but can also provide best practices for consuming and working with the API. The API can include batch features that can be useful for reducing chattiness across services, but if the consumer is not aware these batch features do not help. Swagger (http://swagger.io) is a tool we can use for interactive documentation of our API, as well as client SDK generation and discoverability.