Service Checklist

From n² wiki

Jump to: navigation, search

Nearby: Guides and Tutorials

This page contains a list of things we check when creating or extending a platform service.

URIs are named consistently

  • Platform URIs follow the container/item pattern. The first component of the URI path is the container, the next component an item in that container, the next component a collection of sub-items etc. For example in the URI '/stores/ukbib/services/sparql' there is a container called 'stores', an item in that container called 'ukbib' which has a container called 'services' which, in turn, has an item called 'sparql'
  • All platform URIs are defined to be lowercase and (apart from URI syntax such as / and ?) may only contain the letters a to z, the numbers 0 to 9 and the hyphen -

Every service has a human interface too

  • A human should be able to get an HTML form to fill in by accessing the service URI without any parameters
  • The HTML form should be obtainable by specifying 'text/html' or 'application/xhtml+xml' as a media type in the request's accept header
  • Some services may also present the HTML form if the accept header contains "*/*" or is missing
  • All HTML documents should be well-formed, semantic XHTML 1.0
  • Every parameter supported by the service must be listed in the HTML form
  • All names of form elements that correspond to service parameters must be in lower case

Services allow you to choose the best format

  • Every service has a list of named output types which correspond to output formats. See Output Types for full details.
  • Services with more than one output type must support a query parameter called "output" which allows the user to select the format they want without using Accept headers.
  • If the output parameter is supplied in a request, ignore the Accept header
  • If there is no output paremeter, use the Accept header to determine which output type should be selected

Services are tolerant in what they receive, but strict in what they send

  • If the Accept header is missing from the request, treat it as though it had a value of "*/*"
  • If additional, unknown, query parameters are sent, ignore them
  • If the service accepts RDF ignore any triples that are not understood by the service

Services use HTTP response codes appropriately

  • If a required parameter is missing, use code 400 plus a message saying which parameter was missing
  • If a parameter is malformed, use code 400 plus a message saying which parameter was wrong and what can be done to fix it
  • If an HTTP method is used that isn't supported by a service (e.g. PUT), use code 405 plus a message. Also the Allow HTTP header MUST be sent containing a list of methods that are supported.
  • None of the values in the Accept header match an output type supported by the service, use code 406 plus a message saying that the format requested is not supported.
  • If an item is POSTed to a container the service adds it straight away the response code should be 201 and include a Location header containing the URI that the server gave to the new item
  • If an item is POSTed to a container the service adds queues it for processing then the response code should be 202. If possible the service should include a Location header containing the URI that the server gave to the new item. Retrieving this URI may give a 404 until the item has been processed.
  • If a service accepts XML but the client POSTs or PUTs malformed XML, use code 400 Bad Request
  • If a service accepts XML/RDF but the client POSTs or PUTs XML that doesn't parse as RDF, use code 400 Bad Request
  • If a service accepts some type of RDF but the client POSTs or PUTs RDF that doesn't conform to internal constraints (such as URI naming conventions, or expected triples), use code 422 Unprocessable Entity
  • If the client POSTs or PUTs content with an unsupported media type, use 415 Unsupported Media Type
  • If the server cannot accept content from the client because it is low on storage capacity, use 507 Insufficient Storage

Services are used by machines but debugged by humans

  • Error responses (i.e. any response code starting with 4 or 5) MUST include a textual message of the problem. This must be plain text and be sent with a content type header with a value of "text/plain"
  • All error messages should include a statement of the problem in terms of the input the user gave, plus a suggestion on how to fix it.
  • Stack traces are never, ever sent in the response to a request
Retrieved from "http://n2.talis.com/wiki/Service_Checklist"
Personal tools