Restful api standards

[ben-sagar]

Just copied over (with some minor formatting changes) from what I originally wrote in 2015, so now superseded in some areas by the government API guidance.

The purpose of putting these in here now is to get a review of what needs changing, or whether the whole thing can be dropped.

As an aside - I happen to have come across a couple of cases recently that prompted me to see if it was worth resurrecting this.

[nigejohnson]

In a similar way to a lot of the Government digital service material, this seems to concentrate primarily on publicly accessible REST services. In this day and age we will often be building internal REST services: e.g. we might build an internal system with a RESTful service layer and then hang a number of different client applications and possibly some inter-system integration off that layer. Should the same standards apply there? If "yes" should we refine and expand: e.g. to also support internal authentication mechansims? If not should we limit the scope of this standard to overtly refer to publicly exposed interfaces?

[irisfaraway]

Where is the government API guidance? I wonder if it's worth doing a quick comparison so we can identify what our guide has that this doesn't, and then work out what we can just link off to and what we have to specify ourselves.

[pmshaw15]

Here is the Government API guidance that I could find https://www.gov.uk/guidance/gds-api-technical-and-data-standards.

It looks good enough to use as our main standard and then we could add our own extension where we need it for internal API's etc.

Things like Standard #3 Oauth, #5 naming, #10 JSON object, #13 Hypermedia could be removed from our standard.

I do think that the implementation checklist is useful.

[nigejohnson]

I agree with Paul's approach. There is a lot of overlap between the original written standards and the gov.uk standards, and both are fairly detailed: maintaining and digesting two feels like a lot of work. But having somewhere where can add a "gloss" of our own, especially for purely internal APIs, is sensible too. On specifics, though, I do like the gov.uk emphasis on JSON. XML does feel very heavy-weight and legacy now. Should we say something about transactional boundaries and APIs? For example, cover the points discussed here: https://stackoverflow.com/questions/30213456/transactions-across-rest-microservices (I couldn't see much or anything about that in either doc, but may have missed it). I suppose it's also a shame the whole SOAP/WSDL approach to automated API discovery and client generation seems to have died a death, but possibly because it was over-ambitious and more trouble than it was worth? (That is my only point of slight regret about the fading away of the older style web services in preference to REST). Finally, if we do largely base our own standard explicitly on the gov.uk standard, I guess we have the usual issue about versioning. What do we do when the gov.uk standard changes, and potentially becomes incompatible with our own artefacts, including our "gloss/extension" to those very standards. Of course this is a general problem but the gov.uk API standards last changed on 24th July, so they could be quite fluid. We can (and I'd say should) always reference a specific version of any external standards, even if just by date. But, if we can't rely on the older versions remaining accessible, should we store a copy somewhere?

[ben-sagar]

As agreed in the standards call on 05/10/2020, there is no specific content in here that isn't adequately covered by the latest government API standards. Further Defra-specific standards are largely dependent on defining an approach to API-management and selection of a corresponding technology solution. Consequently, I am now closing this PR.