How to directly access the OT2 Markup Service?

anushibinj · September 17, 2023

This question is in reference to this Viewing Service API Document.

The doc says: "Your integration does not typically have to interact directly with the Markup Service because the viewer's markup API below almost certainly does everything you need."

However, I have a requirement where I want to do "headless" modifications to the markup data for a document. That is, I don't want to open the OT2 Viewer to modify the markup data. For this, I need to interact with the Markup Service directly via REST calls, just like how the rest of the OT2 services are served. How do I do this?

Essentially, I am looking for some services like these:

GET /markup/document-identifier - This should return all the existing markup IDs for a document.
GET /markup/document-identifier/markup-identifier - This should return the markup XML for the given document and markup ID.
POST /markup/document-identifier/markup-identifier - The body of the request should have a markup XML that I want to set for the document.

Edgar Rodriguez · October 12, 2023

Hello,

The markup service uses a GraphQL API; you should be able to perform the desired actions through it.

A couple of GrapQL query bodies as examples:

Query just the markup IDs:

{

"operationName": null,

"query": "query ($source: String!) {markups(source: $source, includeDeleted: false) {id}}",

"variables": {

"source": "<the source value used to save the markups>"

}

Query the IDs and other things, including tags:

{

"operationName": null,

"query": "query ($source: String!) {markups(source: $source, includeDeleted: false) {id type tags { name value }}}",

"variables": {

"source": "<the source value used to save the markups>"

}

One important note:

The GraphQL mutation (markup creation/update) implements a destructive update methodology; whenever the mutation is called, the request body must include the full markup JSON object, not just a subset of updated properties.

Also, the markup data is JSON, not XML.

Regards.

Edgar Rodriguez · October 19, 2023

Hi @anushibinj,

The endpoint to use for the markup service is: /markup/api/v1/graphql.

Regards,

Edgar

anushibinj · October 4, 2023

Can someone please help? Thanks!

Edgar Rodriguez · October 12, 2023

Hello,

The markup service uses a GraphQL API; you should be able to perform the desired actions through it.

A couple of GrapQL query bodies as examples:

Query just the markup IDs:

{

"operationName": null,

"query": "query ($source: String!) {markups(source: $source, includeDeleted: false) {id}}",

"variables": {

"source": "<the source value used to save the markups>"

}

Query the IDs and other things, including tags:

{

"operationName": null,

"query": "query ($source: String!) {markups(source: $source, includeDeleted: false) {id type tags { name value }}}",

"variables": {

"source": "<the source value used to save the markups>"

}

One important note:

The GraphQL mutation (markup creation/update) implements a destructive update methodology; whenever the mutation is called, the request body must include the full markup JSON object, not just a subset of updated properties.

Also, the markup data is JSON, not XML.

Regards.

anushibinj · October 19, 2023

Hi @Edgar Rodriguez,

Thanks for the reply.

Can you please provide the endpoint I need to contact to execute the GraphQL requests? I had already asked a similar question in this post. But I haven't got any reply to it yet.

Thanks