Consistency in the API design

[tmushayahama]

Without getting into style guides and any API design patterns (opinionated things). Whatever design you pick, it should be a consistent API design across all APIs. This will be really helpful to developers consuming it..

There should be a clear definition of resources being exposed by the endpoint (one model or many models etc) like nouns and preferably not verbs (as http verbs cover that). Jumping to an actual example, if getting a list of model resources is GET models/, An assumptions will be made that getting a list associations is GET assciations/ but getting them is GET association/find

Below is an extra (more on this example)

Current Association API

The problem What resource am I getting?, one? many? etc Permutation problem to, from, between Future conflicts GET/association/{id} === GET/association/find/ where id = ‘find’- If(id===‘find’ then GET/association/find else GET/association/{id} ?? Now how to add GET/association/download

Some Potential Solution

Remove secondary(compound) API’s by optional parameters Endpoint to define resource not operations, Http verb, optional parameters Remove ambiguity

Potential Association API

GET/associations/{id}  one resource GET/associations/ many resources with Optional Params 

1. subject_category
2. object_category
3. object,
4. Subject

Usage: To find associations to 'b' GET/associations?object="b" To find associations from 'a' to 'b' GET/associations?subject="a"&object="b" To find associations from 'a' to 'b' with limit of 20 in xml format GET/associations?subject="a"&object="b"&limit=20.xml

tagging @deepakunni3 @cmungall @kltm any thoughts? I don't know what to say when you need more verbs in REST endpoint like /download, /overrepresentation