Adopt controller pattern

[OR13]

This PR builds on the previous one which created "v0.0.2-unstable"

It attempts to formally adopt the controller naming convention, as described here:

https://restfulapi.net/resource-naming/

A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.

This aligns best with the existing APIs, and also avoids some of the complaints regarding REST / HTTP specific interfaces as functional style routes are easier to translate to other transports.

[peacekeeper]

+1.. This is starting to look a bit like the original ​/credentials​/issueCredential and ​/credentials​/composeAndIssueCredential pattern again ;)

[OR13]

@peacekeeper yes, it is, my objective is to adopt a "strategy for naming / structure" and then use that to defend why we choose the structure we have :)

[dlongley]

I'm good with this pattern.

[dlongley]

+1.. This is starting to look a bit like the original ​/credentials​/issueCredential and ​/credentials​/composeAndIssueCredential pattern again ;)

Side note: I think we should use kebab case (lowercase w/hypens) for URLs.

[OR13]

@dlongley @peacekeeper from the same style guide:

https://restfulapi.net/resource-naming/

To make your URIs easy for people to scan and interpret, use the hyphen (-) character to improve the readability of names in long path segments.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  //Less readable

[tplooker]

Question, why not have API's that are more RESTful e.g HTTP POST /credentials which creates and issues a verifiable credential?

[tplooker]

So for example

HTTP POST /credentials <= Creates and issues a verifiable credential
HTTP POST /credentials/verify <= Requests the verification of a verifiable credential

HTTP POST /presentations <= Creates a verifiable presentation (optional signs the presentation)
HTTP POST /presentations/verify <= Requests the verification of a verifiable presentation

[OR13]

@tplooker "RESTful" is not descriptive enough to avoid an endless design debate... this PR attempts to clarify what "flavor" of rest we are agreeing too upfront, so that PRs can be merged according to conformance to style guide.

I think what you are suggesting is the collection style route naming convention....

EDIT: technically in #73 (comment) you are propoosing both collection:

HTTP POST /credentials
HTTP GET /credentials/:credentialId ?
HTTP PUT /credentials/:credentialId ?
HTTP DELETE /credentials/:credentialId ?

and controller:

HTTP POST /credentials/verify

I am not opposed to mixing these, as long as others agree.

[OR13]

One reason to avoid the collection style naming is that is relies on the route to convey information, making it less obvius how to translate the API to none HTTP interfaces.

[tplooker]

One reason to avoid the collection style naming is that is relies on the route to convey information, making it less obvius how to translate the API to none HTTP interfaces.

Yeap understood, r.e mixing the controller and collections pattern, I think if we do add the holder capacity to the API then we will end up mixing anyway

E.g

HTTP POST /credentials/issue
HTTP POST /credentials/verify
HTTP GET /credentials/:credentialId ?
HTTP PUT /credentials/:credentialId ?
HTTP DELETE /credentials/:credentialId ?

Perhaps this ^ is still cleaner though?

[OR13]

@tplooker I like your example.

[tplooker]

Given the conversation im happy with the proposed changes.