As mobility has exploded onto the list of of top IT priorities over the past few years, many IT shops are realizing that one of the first steps in creating mobile apps that make use of data is figuring out how to properly expose that data via web services. Beyond the standard technical recommendations – there are some common architectural design principles to be aware of when designing and building services – whether they’re internal, enterprise services or public-facing mobile web services.
These principles are well documented throughout the internet, but I found it difficult to find a simple, concise, easily digestible format that wasn’t quickly treading into pie-in-the-sky architecture speak. Careful consideration should be given to these principles early in the design process in order to mitigate the downstream impact of poor architectural decisions. Most of these principles are also beneficial to other areas of object-oriented software development (i.e. loose coupling) – however, the below principles will become readily apparent and relevant when building services.
The six principles are:
- Loose coupling
- Autonomy
- Statelessness
- Explicit contracts
- Composability
- Discoverability
Loose Coupling
Several (autonomy, statelessness) of the six principles also assist in the creation of loosely coupled services. A loosely coupled service requires limited knowledge of the definition or inner workings of other components relied upon by the service. The benefit of loose coupling is the flexibility and agility gained by being able to change the inner workings of a service as needed, without having to make related changes to clients or other components relying upon the service. There are a variety of ways in which services can be tightly coupled – for example: contracts, security, technology, and statefulness.
Coupling via the service contract can occur when the contracts are built against existing logic from back-end systems (i.e. using ORM-generated classes that contain every single database field), which can hinder the evolution of a contract as it has not been designed independently of the underlying logic. Coupling via security or technology can occur when a service is based upon security or communication protocols that limit the adoption of the service – for example, a service built upon an outdated technology (i.e. CORBA or .NET Remoting), or a rarely-used security protocol which may not work across all devices. Coupling via state can occur when service operations must be called in a specific order, coupling the service with the order of operations and session state that must be maintained on the server. Coupling against state can also have a negative impact – for example, a step cannot be added into the middle of a process without updating all service clients.
Autonomy
Service autonomy is a design principle that allows for services to operate more reliably by having maximum control over their execution environment and relying as little as possible on the availability of external resources for which they have no control. Autonomy can be increased by running services on dedicated hardware (reducing dependence on other systems running on the same hardware) or by storing cached copies of data, thus reducing dependence on external databases. Not always possible in every scenario, but good to keep in mind.
Statelessness
Requiring that service operations be called in a specific order increases coupling via an implicit contract – meaning that the order in which the operations should be called is not known and documented by the service itself, but rather must be documented via outside knowledge. Reducing state within services allows for services to be more scalable, as the amount of resources consumed by the service to manage and track state information does not increase with the number of consumers. The most common way to reduce service state is to manage all state at the consumption level – forcing the client to keep track of its own state.
Explicit Contracts
Service consumers should rely only upon a service’s contract to invoke and interact with a service and those interactions should be based solely on the service’s explicit contracts, those which are defined by the service itself, e.g. via a WSDL document – rather than any implicit contracts, for example – external documentation.
Several best practices regarding contracts include:
- Ensure that the contract definitions remain relatively stable over time to prevent downstream impacts on the service consumers.
- If the service contracts must be changed, use versioning if possible so that existing consumers are not broken.
- Avoid exposing private, internal data to consumers – remember the object-oriented design principle of encapsulation. Private implementation details (e.g. primary keys, internal flags, etc.) need not be exposed.
- Contracts should be designed to be explicit as possible to prevent errors in interpretation.
Composability
Service composability is a design principle which encourages services to be designed in a way that they can be consumed by multiple external systems. This promotes the reusability and agility within a service-oriented environment, as it allows new systems to be built by re-using existing services. Composability is further enabled by several of the other design principles including Autonomy (increases reliability of the service such that it can be used in other systems) and Statelessness (allows the services to be used in conjunction with other services without regard for state).
Discoverability
Discoverability is a design principle that encourages services to be discovered more easily by adding metadata about how the service should be invoked and interacted with, and storing that metadata in a central repository if possible. By making the services more easily discoverable and cataloging the related information, the services are inherently more interoperable and can be re-used more easily. The core consideration for this principle is that the information catalogued for the services needs to be both consistent and meaningful. The information recorded about the services should be accessible by both technical and non-technical users, allowing anyone to evaluate the capabilities of the service and whether or not it should be used.
Service Design Recommendations
While not all of the services design principles can be followed to the letter in every real-world services implementation, the guidelines can generally be applied regardless of the scenario. The following recommendations should be observed in regards to building well-designed services.
- Limit coupling where possible by limiting the amount of knowledge of inner workings required to consume a service. This allows for more flexibility in consumer systems and the ability to change services more easily.
- Use common, well-supported message formats such as SOAP/XML or REST/JSON and well-supported security paradigms (i.e. token based authentication) to limit coupling via technology.
- Use caching where possible within the services layer to speed data retrieval and response times, and to increase service autonomy.
- Define explicit service and data contracts where possible, and avoid exposing private implementation details – sending only the data necessary to complete a unit of work.
- When making breaking changes to contracts, consider including a version number in the HTTP headers or with the initial login web service call – if the service client or mobile app is out of date, the user can be alerted and directed to the app store for an app update.
- Make services stateless whenever possible to reduce coupling, and if not possible – ensure that state is stored external to the service, e.g. in the session store or cache of your web framework.
- Build systems by re-using existing services when possible to promote service composability and to avoid creating multiple versions of a service method that perform the same business function.