Paradigm X

Vision quests of a soulhacker

A Brief Guide of (RESTful) SOA, Part III

Part I | Part II

In the final part of this article we will discuss several common topics of RESTful web service implementation. I will not dig deep here because all these topics are all quite complicated.

Level IV: RESTful Service Implementation

4.1 Reference Architecture

Reference Architecture

The architecture shows several good start points:

  • Layered system: simple but strict layered system gives reusable and loose-coupled architecture. Every layer in this architecture should able to scale independently.
  • Representation layer: a facade to handle all API requests consistently. Nearly all the common tasks can be centralised here. See section 4.2 below for detail.
  • State/transfer layer: a mid-tier to contain all business logic, including business object and flow abstraction, and the access layers for all back-end resource.
  • Resource layer: can be any resource used in the system. e.g. platform data (structured or unstructured), external data port, adaptors to other resource APIs, etc.
  • Caches: cache any cacheable things. Design a consistent mechanism to manage the caches.
  • Workers: many things should be handled automatically and asynchronously. Build a job system to schedule and manage all automatic workers.

4.2 Facade

An API facade is a centralised entry for all API requests. Requests are pre-processed here and routed to proper business handlers. Return data are also rendered here, as exactly described in the API specs, and response to the client.

Nearly all the common tasks can be centralised here:

  • Authentication, authorisation and auditing (3A)
  • Rate limiting
  • Parameters parsing and checking
  • Return data rendering
  • Statistics and analysis

All these tasks are business independent. Actually they are mostly cross-cutting concerns. For better separation of concerns they should be separated from the main business part and consolidated to a centralised place.

Note that for performance reason some should run asynchronously from the main request/response flow.

4.3 Scaling

Scaling

A well-designed layer system can guarantee independent scaling per every layer. In the reference architecture:

  • The front-end can be horizontally extended by adding a front-end load balancer.
  • The business logic can be horizontally extended by adding a service router and coordinator. By doing this you can even make some intelligent system to dynamic adjust service load via requests stats.
  • The data is the hardest part to be extended, especially for traditional RDBMS. But you can use any mature mechanism to make life better: partitioning, sharding, clustering etc. Another very popular solution is to separate some highly active data and put them into Redis (or other NoSQL system).

Most best practices on Internet-scale services are fully applicable to RESTful services. Just remember to keep an eye on the core principles of REST all the time.

Extended Readings

RESTful web services are not traditional web sites but they share most characteristic features of Internet software architecture. If you are an architect but new to Internet-scale services architecture James Hamilton’s classic thesis is a must-read.

For new software architects this cheat sheet is a good start.

With very similar goal to this 3-parts article, Matt Gemmell has written very good guide for API design and implementation (a little later than my first part). It has very different structure and focus from mine and is definitely another must-read.