How to directly access the OT2 Markup Service?

Options

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:

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

Best Answers

  • Edgar Rodriguez
    edited October 12, 2023 #2 Answer ✓
    Options

    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
    Options

    Hi @anushibinj,

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

    Regards,

    Edgar

Answers

  • Can someone please help? Thanks!

  • Edgar Rodriguez
    edited October 12, 2023 #5 Answer ✓
    Options

    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.

  • 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

  • Edgar Rodriguez
    Options

    Hi @anushibinj,

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

    Regards,

    Edgar