In the beginning of software architecture there were monolithic systems, they had data access codes and business logic combined in the user-interface code. There was no possibility for modularity to exchange layers (for example when the DBMS changes) or the option to reuse components in other applications.
The first change to this architecture was the introduction of layers, specialized on certain concerns of the design. It brought many benefits, such as exchangeability and testability of layers. The execution and deployment is still bound to a single logical executable thought; hence, it can still be called a monolithic kind.
The next adaption to this design was to add interoperability; with the introduction of a public API external process have the possibility to communicate with the application. This can be done by providing a proprietary or customized message format through protocols, such as .NET Remoting, WCF, sockets, and many others.
Nowadays, the trend of designing applications as a suite of fine-grained services is called microservices, which is based on the main idea to orchestrate a bigger system with single-responsibility services. This idea has become more or less standard in the design of Enterprise Applications over the last decade.
The technologies used in the single services are independent, providing the possibility for specialized teams and segregation of internal dependencies. For example, the clients of a data service do not need any information on the actual DBMS, neither do they have a dependency on the used database-specific framework such as NHibernate. The design problems of a single application can be solved in microservices by scaling the services with high demand, which also brings reliability, and then deploying them in a version affine manner to not break usages. This approach also gives you the opportunity to use the tools that fit the concern of the service in the best way, whether it be the programming language or the machine they are running on.
With all this "uncontrolled growth" of services, managed by potentially different teams with different tools with different "thinkings", comes the need for a unified style or a set of the base design guidelines of the internal and external APIs. There are many resources available regarding this issue, I will cover the most important thoughts, which are discussed further in this chapter.
Usually, you are defining an interface for an end user with limited technological knowledge. With services, the audience are programmers, which gives you a technical affine counterpart who may come up with every little flaw in your design. One of the main goals in the design process is to keep it simple, frictionless and understandable to the absolute maximum. Verify the simplicity of the design by letting new people try your API, gather feedback and make the usage a straightforward scenario. Also, avoid the introduction of additional dependencies and unnatural bindings to use your service.
Following a message based communication gives you a top-notch and solid base for solving the design process.
This may only apply to external APIs, but should also be considered for internal ones. Provide example requests and responses, as well as documentation of the DTOs. ServiceStack provides a metadata page to document the requests and responses that also serves as the base for Swagger. You can also add documentation and example code to the operations with Razor views, which is covered in Chapter 5, Documentation and Versioning.
Keep old versions of your API as long as they are needed to ensure that there is no break in the usages. Be consistent with the naming of properties (also take naming practices of the technologies used by clients into account), endpoints, and formats and ultimately push a changelog to ease migration of changes.
The usage of versions is covered in Chapter 5, Documentation and Versioning.
One of the main benefits of using ServiceStack for your service is that you can deal with various input and output formats: You can use QueryString, POST-payload, form-data and even extend this by adding your own format for inputting data. ServiceStack also bundles different output formats and can be enhanced with customized content types.
The format binding is done according to either the value of the Content-Type HTTP header or query string overrides. If you want to implement your own format, you can do so by implementing your own format:
public override void Configure(Container container)
{
this.ContentTypes.Register("application/X-myformat",
(req, response, stream) =>
{
// TODO add your serialization logic
},
(type, stream) =>
{
// TODO add your deserialization logic
});
}Attach validation to your requests as well to provide comprehensible reasons for a failed communication, which is covered in Chapter 5, Documentation and Versioning.
Before any other point on the checklist, there's the encryption of the transport layer with the incorporation of SSL for external services.
Processing a request should always capture the following aspects:
Validate the input
Authenticate the consumer
Check authorization to the operation
Check authorization to the resource of the operation
Authentication can also serve as a base to limit resources for a consumer as well as a common starting point to troubleshoot issues.
ServiceStack also provides several ways to implement authentication and authorization to your service with various providers, which is covered in Chapter 2, ServiceStack as Your Unique Point of Access.
Note
For further information on a lovable API design please read Web API Design – Crafting Interfaces that Developers Love by Brian Mulloy, which can be downloaded at http://apigee.com/about/resources/ebooks/web-api-design.