Currently we're using HTTP Basic authentication and using the supplied credentials as the credentials for database access. So whatever username and password are provided with the request will be used to perform the request on the database.

Clearly https is needed if auth is required and the interface is public!

Current Basic auth leaves db password in browsers auth cache or keychain.

    Digest auth



We use the existing DBIx::Class classes directly as the entity definitions exposed by the data service. This is reasonable given that it's an internal service so there's little value in abstracting it further.

The pattern of set, set/id, set/id/relation, set/id/relation/id can continue to any depth but we're using a flat namespace for now. If we used a deeper path it would represent 'is identified by' (or 'belongs to') relationships. This complicates the caching/invalidation though, so we'll keep it flat for now.

XXX Allow overriding the method via a url param, e.g. for testing: GET /dogs?method=delete TBD

XXX Allow overriding the return status via a url param, e.g. for testing: GET /dogs?suppress_response_codes=true would return 200 status, but the content would still be the error details.

ETag etc [LATER]

For datetime use UTC and ISO8601 - automation via TBD

Review the Web Linking spec (RFC5899) and HAL for use of rel links, eg first/prev/next/last. [LATER]

Formalize the error response contents.


Validation in the data service requires defining an approach to parameter validation (eg adopting a module like Params::Validate plus Moose attribute validations) and defining an approach to throwing and handling exceptions.

Specifically it should provide sufficient information to the client, via the JSON response, to enable the client to update the form to indicate *which* field(s) are associated with the error.

Similarly exceptions raised due to database constraint errors should also generate client-useful exceptions with field information if possible. Note that this may require some mapping of database field names to json entity type field names.


Implementing caching is easy. Implementing efficient caching (where each resource is only cached one - a canonical copy) and cache invalidation (eg a trigger on a table can invalidate the cached copy of affected rows) is, er, non-trivial.


Edge Side Include is the "secret sauce" that enables caching (and cache invalidation) to work nicely with prefetch and HAL.

Consider a simple request like /foo/42. The response looks like:

        id: 42, fields...

A database trigger on the foo table could be used to invalidate the cache for a particular /foo/:id record when that record is updated. So far so good.

Now consider a request with prefetch: /foo/42&prefetch=bar where the response looks like:

        id: 42,
        ...other foo fields...
        _embedded: {
            bar: { id: 97, ...other bar fields...}

Now there's no simple way to invalidate that cached response when the corresponding record in the bar table is updated.

This is where ESI comes in. The response from the API would look like this:

        id: 42,
        ...other foo fields...
        _embedded: {
            bar: <esi:include src="/bar/97">

the ESI processor (eg varnish) caches that unprocessed response and then processes the ESI requests embedded in it. So it makes a separate request for "/bar/97" (which may well be resolved from its own cache) and builds the response to send to the client.

The same database triger mechanism on the bar table will invalidate the cached /bar/97 response when the corresponding record in the bar table is updated.

With ESI, this invalidation affects all cached responses.

Also look into "Surrogate-Capability & Surrogate- Control headers for ESI based block caching"


The varnish cache (see supports basic ESI and also enables alternative approaches that might be useful:

* X-depends-on - e.g.




REST Core concepts and specifications: (HTTP Spec)

Best practice (hint: there's isn't one, just lots of suggestions): (XML) (107 slides)


Example APIs

API Design

Linking (see also the comments)

HAL - Hypertext Application Language

URI Template

CURIE Syntax - Compact URIs

Partial reponses

Other references:

Restful Objects:
    Demo: (video)

Assorted Proposed Standards

Error Formats