Konzept #587

API design

Added by Alexander Blum about 6 years ago. Updated almost 5 years ago.

Status:NeuStart date:
Priority:NiedrigDue date:
Assignee:-% Done:


Category:-Estimated time:2.00 h
Target version:Repertoire 3) Testing phase III


This might maybe more a question of taste. Right now, we have apis for datatables (/datatables/v1/) and for jQueryUpload (/repertoire/v1/), which fit the needs of the libraries (e.g. for datatables: total records, offset, limit, request id). At some point in time, we want to change the list views to datatables and need to implement more filter functions. The question is, if we should build more and more special case apis, or a general api for all objects and all usecases (public, datatable ajax calls, internal/foreign services, etc.). Right now we have:

  • /repertoire/v1/

    • upload
    • list
    • show
    • preview
    • delete
  • /datatables/v1/

    • artists

Christoph and Markus once had some reading material about apis, maybe they could give some feedback on this.


#1 Updated by Alexander Blum over 5 years ago

  • Target version set to 3) Testing phase III

#2 Updated by Alexander Blum over 5 years ago

  • Estimated time set to 2.00

#3 Updated by Alexander Blum almost 5 years ago

  • Target version changed from 3) Testing phase III to Repertoire 3) Testing phase III

#4 Updated by Alexander Blum almost 5 years ago

  • Project changed from repertoire to collecting_society

#5 Updated by Markus Lorenz almost 5 years ago

I think the important question is what you are serving with the API.

/repertoire/ looks like a general purpose API which C3S provides and which could be used by mobiles apps or desktop applications as well as other services. In this case C3S is the owner of the API and can dictate the design. It should follow best practices.

In case of DataTables, which I believe references the jQuery plugin, you don't have much of a choice if you don't want to fork the plugin to make it suit your API. DataTables expects a certain API which you have to provide. How you provide it is another question. An adapter on top of the general purpose API might be one solution, just wrapping and translating the API access. This hopefully keeps the additional code lightweight. Furthermore, though it must be publicly accessible for the browser to send requests, it should not be advertised or documented publicly.

Also available in: Atom PDF