Management API

[JavierLuna]

Description of the problem

I'm currently using INCEpTION in an automated pipeline. I've been using INCEpTION's API to interact with it, but the API itself is very limited: It only allows basic CRUD operations and import/export of projects.

I would like to perform some management operations via API as well:

• [ ] Create users and update their permissions
• [x] Assign users to a given project (done via https://github.com/inception-project/inception/issues/3142)
• [ ] Configure a given project: KBs, tagsets... (comment by @reckart : that would create a huge API - it is already possible to create a project ZIP containing a JSON file where all the settings are available. IMHO that should be used instead.)
• [ ] Update the status of an user's annotation (I want to be able to lock annotations for a given annotator)
• [ ] Bulk upload operations. Calling POST - /document a couple thousand times is slooow.

Those are only examples of what I'd want to do, but I see as beneficial having a proper management API (in addition to the AERO one).

Describe the solution you'd like Having a management API in addition to the AERO one. See the description above for examples of services.

Describe alternatives you've considered Right now, I'm exploiting the import/export functionality to more or less achieve what I want to do, but it is very tedious and is definitively not the way to go.

Also, I've considered developing an extension of pycaprio which allows database changes, but I don't feel like that's the proper way as well.

What do you think?

---

Related issues

• Change status of annotation documents from API #2048

[reckart]

AERO tries to capture functionality which is quite common between annotation tools - the idea is to have a protocol that different tools could implement.

I think some of the things you are missing in the AERO API may be quite common and are kind of missing from the API, e.g. a basic user management API or the ability to link users to projects.

Other things like KBs or tagsets are quite a bit more specific. One could consider to add a remote API for them - but I wonder: how often do you need to manipulate these while a project has already been set up. Even as you explain it, I would think you only need a one-time setup API for these - maybe you can describe a bit more on what your scenario is?

Writing directly to the database doesn't seem like a good idea. But maybe implementing an offline "builder" for project configurations?

[JavierLuna]

I work for a company where we use INCEpTION at scale. We generate a couple of projects per day, with different configurations each, in different INCEpTION instances.

Those projects and document uploading/downloading are handled in an automated pipeline, using INCEpTION's API.

Although the basic operations work for us, we have a lot of use cases (the ones I mentioned in my first comment are the most common ones) that cannot be automatically executed via API.

This adds great toil in our operations resulting in a huge time loss for our team. I understand "one time" operations may not seem like a waste of time, but it is more like a lot of "one time" operations adding up.

I have a project builder in place already, that uses the import/export mechanism to kind of achieve what I want, but I don't feel like meddling with the zip file is the proper way to do the things I mentioned earlier.

Thank you for taking a look at this.

[ofersabo]

We work on a project builder code that can create new projects and push them into inception based on the JSON file in the project home directory. One major thing that we do is to create multiple projects of the same assignment given the number of taggers that we have, and the amount of overlap that we want them to have. Let's say we have X annotators and we want 0% overlap then we would generate X projects, one for each annotator. We would split the number of reports evenly across annotators.
On the other hand, if we want 100% overlap then we create a single project. So this is how we generate the number of projects based on X and the overlap value.

Hopefully, we'd be able to share this code soon.

There is something that we can't find a way to do, and since it was mentioned here I hope some here could advise. Changing the status on an annotated document, for example, locking or unlocking some document.

[reckart]

@ofersabo I believe for the aspect you mentioned above, you also created #2048 which has meanwhile been addressed - correct?

[ofersabo]

Yup. Thanks

[reckart]

@ofersabo Are you still working on the project builder code? Have you published it anywhere?