REST Web Service API Guidelines

When building web services, one of the primary benefits of using REST over SOAP is the intuitive nature of service interfaces.  However, this simplicity of interface can very easily be eroded.  Below are some suggested (and hence flame proof) guidelines that could be followed to ensure continued interface simplicity:

Resource-Oriented

• REST is resource-oriented, not service-oriented.  Resources are nouns, not verbs.

Addressable

• Every resource must be addressable by means of at least one URI (name).  Names must be meaningful.
• Clients cannot access resources directly - they deal in representations of that resource (e.g, XML, JSON, ...)  
• Resource representations would ideally be addressable (so that they can be passed around as URIs, eg. /rest/bookmarks.xml)  The use of HTTP accept headers to specify representation is however acceptable, but should be provided as well as the addressable URI.

Read More

REST Web Service Paradigm Shift

Moving your Service-Oriented Architecture (SOA) from RPC style (web) services to SOAP document-oriented services, or REST resource-oriented services requires a difficult mental paradigm shift.  The same kind of shift that was required for monolothic and procedural programmers to move to object-oriented programming styles.  This change is not easy, and not all will pass muster.  Failing to make the change will mean the difference between Just a Bunch of Web Services (JABOWS) or a fully-fledged SOA.

Ensuring that this mind shift does happen will require good organisation and strong, well-articulated guidance and governance.  Until the new pattern becomes habit, people will very quickly slip into old habits. 

Below are some guidelines and implementation suggestions from this blog:

• Key REST service guidelines
• REST service naming guidelines
• REST service error handling
• Service design principles
• A plea for HATEOAS
• HTTP error code guidelines

Read More

REST Web Service Spring Error Handling

The Spring framework provides excellent support for building REST web services in a service-oriented architecture (SOA), as I have demonstrated in a previous post, but what is not immediately obvious is how best to deal with errors. Instead of throwing raw exceptions to the client, one would prefer to return a well-formed response consisting of an appropriate HTTP status code and a meaningul response body containing a structured error message in the response form (JSON, XML, ...) requested by the client.

For example, assuming you have a basic REST endpoint such as:

 @RequestMapping(value = "/samples", method = {RequestMethod.GET})
 @ResponseBody
 public SampleList findAllSamples() throws SampleException {
  return new SampleList(service.findAllSamples());
 }

It is good practice in general to not let implementation exceptions leave the service tier, so you might use aspects to catch these and rethrow them as service exceptions.  The code below catches a ReferenceNotFoundException from the data access tier and throws a service exception with the reference number and setting the desired http status code.  Another good practice is to avoid sending free text error messages to a service client, and instead to send structured messages that can be dealt with or rendered as the client sees fit.

@Aspect
@Component("exceptionHandler")
public class ExceptionHandler {

   /**
    * Exception handler for ReferenceNotFoundExceptions
    * 
    * @param nfe the exception being handled
    */
   @AfterThrowing(pointcut = "execution (* com.sample.service.*.*(..))", 

                                              throwing = "nfe")
   public void handleNotFoundException(ReferenceNotFoundException nfe) {
      throw new SampleException(
         new ReferenceNotFoundError(nfe.getReference()), 

                               HttpStatus.NOT_FOUND);
   }

Now to map the service exception (SampleException) to a meaningful HTTP response using the Spring 3 @ExceptionHandler annotation:

   @ExceptionHandler(SampleException.class)
   @ResponseBody
   public SampleErrorList exceptionHandler(SampleException se,
                 HttpServletRequest req,
                 HttpServletResponse res) throws IOException {

      res.setStatus(se.getHttpStatus());

      return new SampleErrorList(se.getErrors());

   }
 

It is also possible to set the HTTP status code using an annotation, but in this example the exception determines this, so the handler sets it programmatically.

See here for a downloadable working sample.

REST Web Service Spring Error Handling

Read More

Web Service API Management

Service-oriented Architecture (SOA) web service API operations management requires a sophisticated service management organisation which is capable of defining and sustaining service levels to its customers across the enterprise. SOA without the service management will result in greater systems fragility and chaos.

ITIL is the widely adopted framework for implementing service management practices and so it figures that it would have relevance to SOA. Under ITIL services must become managed and supportable enterprise assets. This has the following requirements for an organisation:

Read More

Public Web Service API Management Solution

So, as part of your Service-oriented Architecture (SOA) strategy, you've decided to join the Web 2.0 rush to publicise your web service APIs and are wondering about how you might manage this.  Do you build something or are there 3rd party products to help?  The buy-vs-build decision is always a tough one, but you will need to consider your core business and competencies, as well as the product's support for the following:

Partner website - a public portal where consumers of your services will be able to register, obtain service keys, documentation, support, raise issues, join mailing lists, subscribe to RSS updates, download client libraries etc.

Key management - provision and management of API keys and ensure those are supplied with calls.  Support for OAUTH

Read More

Extensible Web Service API

The only constant in life is change, and this is no different for Service-oriented Architecture (SOA). Services must be built with this in mind: that they will have to adapt to new or changing requirements. Extensibility is the ability for services to adapt whilst preserving existing consumer contracts.

We would expect the following types of changes to services to have no impact on other consumers:
- internal source code changes
- interface changes
- take on of new consumers
- environmental changes

Read More

What is Service-Oriented Architecture (SOA) - Competitive Services

I have been reviewing ITIL 3 with a view to updating my article on Service Management, and came across the notion of competitive services.

This is a very common notion when one looks at services in the usual, non-SOA sense where services are being offered in a market place and have to compete, but does it apply to SOA?

Well, clearly if you are looking at services offered in the internet by companies engaged in Cloud computing and such like, e.g. Google or Amazon, the answer is yes, but what about your typical corporate enterprise landscape?

Read More

Building a REST Java web service API using the Spring framework

Building a REST-ful Java web service API has never been more restful than now, using version 3+ of the Spring framework.

 First some annotated Java code:

@Component
@Controller()
public class SampleController {

     @Autowired
     private SampleService service;

     @RequestMapping(value = "/samples/{reference}", method = {RequestMethod.GET})
     @ResponseBody
     public Sample getSampleByReference(@PathVariable String reference) {
          return service.getSampleByReference(reference);
      }
 }

Read More

Java as a Service - Monitoring the Java Web Service API

One key aspect of managing your public REST web service API is understanding your client usage.

There are several options for doing this, including configuring your IP sprayer to do quota management, or facading your services with a 3rd party service management product like Layer 7 or SOA Software, but you might also consider the very simple Java web service based solution using the open source JAMon library.

The sample code below illustrates a simple per-IP address monitoring solution that you might customise to be per-account or whatever else is available in the HTTP request header.

Read More

What is Service-Oriented Architecture : Service Characteristics

The full series of posts on Service Characteristics:

Service Characteristics - Contract
Service Characteristics - Abstract
Service API Characteristics- Composable
Service API Characteristics- Autonomous
Service API Characteristics - Discoverable
Service API Characteristics - Distributed
Service API Characteristics - Reusable

These will apply whether you are writing RMI, CORBA, SOAP or REST web service APIs.

Read More

REST Web Service API - Naming Guidelines

The following offers a suggested set of URI naming guidelines for REST web service APIs that have worked for me in practice.

The book RESTful Web Services RESTful Web Services defines three basic rules for url design which act as a great starting point:

• Use path variables to encode hierarchy: /parent/child 
• Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2 
• Use query variables to imply inputs into an algorithm, for example: /search?q=jellyfish&start=20 

Read More

What is Service Oriented Architecture - Loosely Coupled Services

What does it mean for a service to be loosely coupled in a Service-Oriented Architecture?

A service is said to be loosely coupled if its consumers are minimally impacted by changes to that service or its environment. Some coupling is obviously inevitable since the consumer has to make use of the service but can be minimised in a number of ways:

Read More

REST Web Service API Documentation using RESTdoclet

IG Group has open-sourced RESTdoclet, a maven plugin for generating web-based REST API documentation from REST Java web services implemented using the Spring REST framework.

The plugin:

·         supports Spring 3 REST annotations and JavaDoc out of the box,

·         does not require any additional annotations,

·         is easily integrated with Maven continuous build processes, with minimal configuration,

·         supports multiple streams of service development, and

·         publicises documentation in an interactive, Javadoc-like form, to the web, thus providing a source-code agnostic guide to service consumers.

Read More

What is SOA - Service Characteristics - Composable

Composability is the ability of services to be used in orchestration scenarios by higher level services or processes. It is a special case of the reusability characteristic in that the services need to be uniform as well as reusable. The reason for this primary reason for this requirement is that the orchestrating service will in all probability but built using something like BPEL not a conventional programming language, so any variations in service style become more difficult to deal with.

Read More

What is SOA - Service Characteristics - Abstract

Services must be abstract in the sense that they offer a functional interface that is not tied to any particular underlying implementation of that interface. In other words they should hide implementation details such as programming language, operating system platform, database structure, internal object model, etc. Abstraction supports other service characteristics such as reusability, extensibility and reduces coupling between producer and consumer.

Read More

What is SOA - Service Characteristics - Autonomous

A service is autonomous if it has full control over its internal logic. This requires that it has clearly defined and isolated (decoupled) functional and operational boundaries, that it is independent of other services and only communicates via contract-driven messages and policies.

A consumer should exercise no influence over the service other than to execute it and to provide input values. The service should have minimal dependency on its execution environment.

Read More

What is SOA - Service Characteristics - Discoverable

For services to be of use of anyone they must be discoverable. Discoverability is usually taken to refer to the ability for consumers to find a relevant service by attributes (tags) at runtime via a service registry. In other words, consumers go to a service “yellow pages” and find at runtime services that best meet their needs.

Read More

What is SOA - Service Characteristics - Stateless

A service is said to be stateless if the consumer of that service can make use of any operating instance of that service. This is achieved by services not storing any internal data (state) that would be required if the consumer happened to invoke another instance of that service.

In general this goal is achieve by ensuring that all service data (including state) is kept in an external store common to all instances of that service.

Read More

What is SOA - Service Characteristics - Distributed

Services should be distributable, that is they need not and indeed should not run in the same process as the consumer. Services that run in the same process offer no possibility of runtime reuse to other consumers.

In order to achieve this goal you minimally need two things: a remoting framework and location transparency

Read More

SOA Web Service API Management

I have written and published an article at SOA World on SOA Web Service API Management and ITIL.

Read More