REST API: How to discover a resource's methods

Refer to the How to discover the resources available documentation to learn where to get the Discovery Document discussed below.

In a Discovery Document's resource's methods object, all methods you can perform on a resource are detailed. For example, a Conctact's methods might look like this:

    "Contact": {
      "methods": {
        "delete": {
          "id": "Contact.delete",
          "path": "contact/{number}",
          "httpMethod": "DELETE",
          "description": "Deletes a single Contact record.",
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact"
          ],
          "parameters": {
            "number": {
              "type": "string",
              "location": "path"
            }
          },
          "parameterOrder": [
            "number"
          ]
        },
        "get": {
          "id": "Contact.get",
          "path": "contact/{number}",
          "httpMethod": "GET",
          "description": "Gets a single Contact record.",
          "response": {
            "$ref": "Contact"
          },
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact.readonly"
          ],
          "parameters": {
            "number": {
              "type": "string",
              "location": "path"
            }
          },
          "parameterOrder": [
            "number"
          ]
        },
        "head": {
          "id": "Contact.head",
          "path": "contact/{number}",
          "httpMethod": "HEAD",
          "description": "Returns the HTTP Header as if you made a GET request for a single Contact record, but will not return any response body.",
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact.readonly"
          ],
          "parameters": {
            "number": {
              "type": "string",
              "location": "path"
            }
          },
          "parameterOrder": [
            "number"
          ]
        },
        "insert": {
          "id": "Contact.insert",
          "path": "contact",
          "httpMethod": "POST",
          "description": "Add a single Contact record.",
          "request": {
            "$ref": "Contact"
          },
          "response": {
            "$ref": "Contact"
          },
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact"
          ]
        },
        "list": {
          "id": "Contact.list",
          "path": "contact",
          "httpMethod": "GET",
          "description": "Returns a list of Contact records.",
          "parameters": {
            "maxResults": {
              "type": "integer",
              "description": "Maximum number of entries returned on one result page. Optional.",
              "format": "int32",
              "minimum": "1",
              "location": "query"
            },
            "q": {
              "type": "string",
              "description": "Free text search terms to find events that match these terms in any field. Optional.",
              "location": "query"
            },
            "pageToken": {
              "type": "string",
              "description": "Token specifying which result page to return. Optional.",
              "location": "query"
            }
          },
          "response": {
            "$ref": "ContactListItem"
          },
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact.readonly"
          ]
        },
        "listhead": {
          "id": "Contact.listhead",
          "path": "contact",
          "httpMethod": "HEAD",
          "description": "Returns the HTTP Header as if you made a GET request for a list of Contact records, but will not return any response body.",
          "parameters": {
            "maxResults": {
              "type": "integer",
              "description": "Maximum number of entries returned on one result page. Optional.",
              "format": "int32",
              "minimum": "1",
              "location": "query"
            },
            "q": {
              "type": "string",
              "description": "Free text search terms to find events that match these terms in any field. Optional.",
              "location": "query"
            },
            "pageToken": {
              "type": "string",
              "description": "Token specifying which result page to return. Optional.",
              "location": "query"
            }
          },
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact.readonly"
          ]
        },
        "patch": {
          "id": "Contact.patch",
          "path": "contact/{number}",
          "httpMethod": "PATCH",
          "description": "Modifies a single Contact record. This method supports JSON-Patch semantics.",
          "request": {
            "$ref": "Contact"
          },
          "response": {
            "$ref": "Contact"
          },
          "scopes": [
            "https://your-demo.xtuplecloud.com/your-db-name/auth",
            "https://your-demo.xtuplecloud.com/your-db-name/auth/contact"
          ],
          "parameters": {
            "number": {
              "type": "string",
              "location": "path"
            }
          },
          "parameterOrder": [
            "number"
          ]
        }
      }
    },

Each method contains a "path" property and an "httpMethod". Some methods contain "parameters" in their path. With this information, you can construct the URL to call the method at. For example, the "get" method above as these properties:

"path": "contact/{number}",
"httpMethod": "GET",
"parameters": {
  "number": {
    "type": "string",
    "location": "path"
  }
},

As you can see, the "path" property uses a URL template. The token, "{number}" is refering to the "number" in the "parameters" section. This tells you that "number" is actually a string and it should be located in the path, not as a query string parameter. e.g. "contact/forty-two" NOT "contact?number=forty-two".

The Discovery Document also contains a "baseURL" property that looks like this:

"baseUrl": "https://your-demo.xtuplecloud.com/your-db-name/api/v1alpha1/",

Combining all of those properties, you can determine how to properly call a resource method. For example, the cURL command to GET Contact "forty-two" would look like this:

curl "https://your-demo.xtuplecloud.com/your-db-name/api/v1alpha1/contact/forty-two?access_token=ec781e69-9fd4-4f67-b86a-28599dd901da"

Note: You will need an Access Token to make this request. See the How to discover the OAuth 2.0 Scope of a method documentation on how to determine the proper scope for a resource and get an Access Token from the OAuth 2.0 Server.

Some methods have "parameters" with a "location" of "query". These parameters should be appended to the URL as a query string. For example, the "list" method on the "Contact" resource takes a search query parameter, "q". To search all Contacts for a Contact containing the text of "blue" the cURL command would look similar to this:

curl "https://your-demo.xtuplecloud.com/your-db-name/api/v1alpha1/contact?q=blue&access_token=ec781e69-9fd4-4f67-b86a-28599dd901da"

Most methods contain a "request" and/or "response" property. These properties tell you what format to expect in response from a resource method and what format to use for your request body when you make a request to a method.

  "request": {
    "$ref": "Contact"
  },
  "response": {
    "$ref": "Contact"
  },

The "request" and "response" properties use a JSON-Schema reference token, "$ref", to tell you which JSON-Schema the "request" or "response" format is in. Refer to the REST API: How to discover a resouce's JSON-Schema documentation to learn more about how to work with JSON-Schema references.

You will want to ensure your requests conform to the JSON-Schema when you make them. You can use the response schema to determine how to display a resource or build an edit form for it.