Skip to main content

API design

Principles of the API design:

  1. All documented routes should be appended to https://blisk.ijs.si/api/.
  2. All the routes are available as POST calls, even if they do not result in changes in the database, because:
    • some routes will have non-trivial input parameters (structured data, arbitrary strings), which are difficult and clunky to encode as path parameters, and expecting request body parameters in GET calls can be problematic and misleading
    • we can have short clear URLS for all routes, and there are limits on URL length in some contexts.
  3. Some routes also have a GET counterpart, which behave the same way as the POST call but do not allow for response body parameters (default values are used instead).
  4. All request parameters are provided as JSON request body parameters, except for the object's id, which is used to identify a given object and provided as an obligatory path parameter for certain types of calls (e.g., retrieve).
  5. Each route falls under a particular type of operation identified with a particular verb as the first part of the route. The verbs include:
    • retrieve: return data for a given object
    • search: return all the objects which match the set of search parameters
    • create: create a new object based on the parameters provided, unless a matching object already exists and only one is allowed (we almost called this "get_or_create" instead)
    • update: update the properties of a given object based on the parameters provided
    • delete: delete a given object
    • attach: attach the given object to a particular resource, if not yet attached
    • detach: detach the given object from a particular resource, if attached
    • process: process the input data with an appropriate independent tool (e.g., the CLASSLA NLP library)
  6. If the operation verb has a "-batch" suffix, it differs from its non-batch counterpart as follows:
    • each item in the input is processed (allowing users to make just a single API call)
    • the input data should be a list, with each element in the format expected by the non-batch route
    • the output data hierarchy has an extra level at the top with two fields
      • results: a list of output data, each corresponding to the input data at the same position in the input
      • errors: a list of errors during processing, in which the position of the problematic item is also included (in which case the item will be null in the results)
  7. Routes which do not change data in the database (retrieve, search, process) are publicly available. Routes which may result in changes in the database (create, update, delete, attach, detach) require authentication credentials.
Back to top