MarkLogic Server REST Application Developer’s Guide 2 MarkLogic 9 May, 2017 Last Revised: 9.0-8, December 2018 Copyright © 2019 MarkLogic Corporation. All rights reserved. MarkLogic Server Version MarkLogic 9—May, 2017 Page 2—REST Application Developer’s Guide MarkLogic Server Table of Contents Table of Contents REST Application Developer’s Guide 1.0 Introduction to the MarkLogic REST API ...................................................13 1.1 Capabilities of the REST Client API ....................................................................13 1.2 Getting Started with the MarkLogic REST API ...................................................14 1.2.1 Preparation ................................................................................................14 1.2.2 Choose a REST API Instance ...................................................................15 1.2.3 Load Documents Into the Database ..........................................................15 1.2.4 Search the Database ..................................................................................16 1.2.5 Tear Down the REST API Instance ..........................................................18 1.3 REST Client API Service Summary .....................................................................18 1.4 Security Requirements ..........................................................................................21 1.4.1 Basic Security Requirements ....................................................................21 1.4.2 Controlling Access to Documents and Other Artifacts ............................22 1.4.3 Evaluating Requests Against a Different Database ..................................23 1.4.4 Evaluating or Invoking Server-Side Code ................................................24 1.5 Terms and Definitions ..........................................................................................24 1.6 Understanding REST Resources ...........................................................................25 1.6.1 Addressing a Resource ..............................................................................25 1.6.2 Specifying the REST API Version ...........................................................26 1.6.3 Specifying Parameters in a Resource Address .........................................26 1.7 Understanding the Example Commands ...............................................................27 1.7.1 Introduction to the curl Tool .....................................................................27 1.7.2 Modifying the Example Commands for Windows ...................................28 1.8 Overriding the Content Database ..........................................................................29 1.9 Performing Point-in-Time Operations ..................................................................29 1.10 Controlling Input and Output Content Type .........................................................31 1.10.1 General Content Type Guidelines .............................................................31 1.10.2 Details on Content Type Determination ...................................................32 1.10.3 Example: Inserting and Reading a Document ..........................................34 1.10.4 Example: Inserting and Reading Metadata ...............................................34 1.10.5 Example: Documents With No or Unknown URI Extension ...................35 1.10.6 Example: Mixing Document and Non-Document Data ...........................36 1.11 Error Reporting .....................................................................................................37 2.0 Administering REST Client API Instances ..................................................39 2.1 What Is an Instance? .............................................................................................39 2.2 Creating an Instance ..............................................................................................40 2.3 Example: Creating an Instance .............................................................................42 2.4 Removing an Instance ...........................................................................................43 MarkLogic 9—May, 2017 REST Application Developer’s Guide—Page 3 MarkLogic Server Version MarkLogic 9—May, 2017 Table of Contents 2.5 Retrieving Configuration Information ..................................................................44 2.5.1 Retrieving Configuration for All Instances ..............................................44 2.5.2 Retrieving Instance Configuration by Content Database .........................45 2.5.3 Retrieving Instance Configuration by Instance Name ..............................46 2.6 Configuring Instance Properties ...........................................................................47 2.6.1 Instance Configuration Properties ............................................................48 2.6.2 Listing Instance Property Settings ............................................................49 2.6.3 Setting Instance Properties ........................................................................50 2.6.4 Resetting Instance Properties ....................................................................52 3.0 Manipulating Documents .............................................................................53 3.1 Summary of Document Management Services ....................................................53 3.1.1 Summary of the /documents Service ........................................................54 3.1.2 Summary of the /graphs Service ...............................................................55 3.2 Loading Content into the Database .......................................................................55 3.2.1 Loading Content .......................................................................................56 3.2.2 Adding Metadata .......................................................................................57 3.2.2.1 Inserting or Updating Metadata .................................................57 3.2.2.2 Example: Replacing One Metadata Category Using XML .......58 3.2.2.3 Example: Replacing Multiple Metadata Categories Using XML . 59 3.2.2.4 Example: Replacing Multiple Metadata Categories Using JSON 59 3.2.3 Loading Content and Adding Metadata in the Same Request ..................60 3.2.3.1 Loading Content and Metadata Using Request Parameters ......60 3.2.3.2 Loading Content and Metadata Using a Multipart Message .....61 3.2.4 Automatically Generating Document URIs ..............................................62 3.2.5 Loading Triples .........................................................................................63 3.2.6 Controlling Access to Documents Created with the REST API ...............64 3.2.7 Transforming Content During Ingestion ...................................................64 3.3 Retrieving Documents from the Database ............................................................65 3.3.1 Retrieving the Contents of a Document ....................................................65 3.3.2 Retrieving Metadata About a Document ..................................................65 3.3.3 Retrieving Content and Metadata in a Single Request .............................66 3.3.4 Transforming Content During Retrieval ...................................................67 3.4 Partially Updating Document Content or Metadata .............................................68 3.4.1 Introduction to Content and Metadata Patching .......................................68 3.4.2 Basic Steps for Patching Documents ........................................................70 3.4.3 XML Patch Reference ..............................................................................70 3.4.3.1 patch ..........................................................................................71 3.4.3.2 insert ..........................................................................................72 3.4.3.3 replace .......................................................................................73 3.4.3.4 replace-insert .............................................................................75 3.4.3.5 delete .........................................................................................78 3.4.3.6 replace-library ...........................................................................79 3.4.4 Managing XML Namespaces in a Patch ...................................................80 Page 4—REST Application Developer’s Guide MarkLogic Server Table of Contents 3.4.5 XML Examples of Partial Updates ...........................................................81 3.4.5.1 Example cURL Commands .......................................................82 3.4.5.2 Example: Inserting an Element .................................................82 3.4.5.3 Example: Inserting an Attribute ................................................83 3.4.5.4 Example: Inserting a Text Node ................................................83 3.4.5.5 Example: Inserting a Comment or Processing Instruction ........84 3.4.5.6 Example: Multiple Inserts in One Patch ...................................84 3.4.5.7 Example: Replacing an Element or Element Contents .............85 3.4.5.8 Example: Replacing an Attribute Value ....................................86 3.4.5.9 Example: Replacing or Inserting an Element in One Operation ... 86 3.4.5.10 Example: Replacing or Inserting an Attribute in One Operation .. 87 3.4.5.11 Example: Deleting an Element or Attribute