API
Coscine offers an Application Programming Interface (API) for the automization of workflows.
Coscine REST API
You can interact with Coscine via a REST API (REpresentational State Transfer). For this purpose you need an access token. The process of creating an access token in your user profile is described in Access Token. To become familiar with API functions and how to use them you should take a look at the documentation of the specific endpoints. There you are able to test certain functions with custom parameters.
API documentation
The Coscine REST API was designed and documented with Swagger. On the dedicated API documentation page you will find information on the endpoints of the API and are able to directly test the API with your API token. Alternatively there is a second documentation which provides executable examples in various programming languages for all Coscine API endpoints.
Coscine API Swagger documentation Interactive Coscine API Documentation
Important information
Rate limiting
Coscine limits the API requests per minute to 500, i.e. you may not make more than 500 requests within one minute. If this threshold is exceeded, your requests may be ignored by Coscine for some time. The purpose of this is to avoid overloading the Coscine servers - be it unconsciously or deliberately with malicious intent. Developers who use a sequential connection to the API will most likely not exceed the threshold. However, if you parallelize certain processes or send asynchronous requests, you should think about how you can stay below 500 requests per minute beforehand. It doesn't hurt to do a little calculation in advance to get a rough estimate of the average API usage. To do this, simply select a variable round trip time (RTT) and multiply this by the number of requests X that you can send in parallel or asynchronously or will achieve as a maximum. If you use a ThreadPool, for example, this would correspond to the number of threads used. If it takes an average of 0.5 seconds for your request to reach Coscine and you receive a response, you can send X requests per 0.5 seconds. For example, if your X=8 and RTT=0.5s, you can send 8*(1/0.5s) = 16 requests per second.
If you multiply this by 60 seconds, you get you get the expected requests per minute (under optimal conditions) - so In our example calculation, this would be 960 requests per minute, which means that we have This means that we have almost doubled the permitted 500 per minute.
Page Size
Some API endpoints work with large amounts of data. To avoid having to send all this data at once in a large response, Coscine divides large amounts of data into many smaller ones (pages) and indexes each of these with an index. You can define the size of these pages, i.e. the number of elements they contain, but the maximum number of elements per page is limited to 50. You can also request individual pages via their index. It is important to note that the index changes depending on the selected number of elements. The number of pages also changes. To obtain all the data of a paginated endpoint, you must request all pages and merge the results at the end.
File Actions
Coscine offers so-called presigned URLs for files in resources, which give users direct access to files without having to legitimize themselves beforehand using an API token. These URLs are valid for a period of 24 hours and expire after this period. To maintain their validity, the URLs must be requested again via a new request. Coscine creates the URLs automatically on the server side.
Using the API
Via an existing API client
You can use the Coscine REST API with a variety of programming languages. A client library in the Python programming language is currently actively maintained by the Coscine userbase:
Coscine Python SDK Coscine Python SDK Dokumentation
Please contact us, if you have written any Tutorial for Coscine on your own! We'd love to share your Tutorials with the Coscine Community on GitLab. Coscine and its users profit directly from the contributions of the Open Source Community. Together we can strive for more - therefore you should not hesitate to make your work public if it does not put you at a disadvantage.
Development of a custom API client
Via Swagger you can create API clients for Coscine in various programming languages. Simply
download the swagger specification of the Coscine API, decide on a programming language and
run the Swagger codegen tool.
You can use this to create a custom client which you can then modify to fit your needs, in case
the existing options like the Coscine Python SDK do not tick all the boxes.
You can find more information on the process in the official documentation pages of the Swagger project.
Autogenerated Swagger API Clients Coscine API Swagger specification
Help with the technical adaption
Within the Coscine community, the Coscine Technical Adaptation Group (CTA) has formed to support researchers in the technical adoption of Coscine. Specifically, scripts, programs, best practices, and consulting services are communicated to users. In order to provide the broadest possible range of support, user collaboration is encouraged. Community projects that are also of interest to other researchers are always welcome and will therefore be included on the groups website and communicated to users. The CTA group is in constant exchange with Coscine users and the Coscine development team itself and is therefore always aware of the latest developments or feature requests. For more information, please visit the CTA Group landing page:
There you will also find a possibility to get in touch with members of the group.