REST API: How to discover a resource's relations to other objects

Review the How to discover the schema of a resource documentation for an introduction on JSON-Schema.

Notice that the JSON-Schema for Contact has "$ref" references within it. There are three types of child relations references you can find within a JSON-Schema parent object.

toOne Nested Child Object:

        "address": {
          "title": "Address",
          "type": "object",
          "$ref": "AddressInfo"
        },

When you GET a Contact resource, it will have a property "address" that will have an "AddressInfo" object nested inside of it. To discover what the "address" property will contain, you should find the "AddressInfo" JSON-Schema. It will look similar to this:

    "AddressInfo": {
      "properties": {
        "number": {
          "title": "Number",
          "isKey": true,
          "required": true,
          "type": "string"
        },
        "isActive": {
          "title": "Is Active",
          "type": "boolean"
        },
        "line1": {
          "title": "Line1",
          "type": "string"
        },
        "line2": {
          "title": "Line2",
          "type": "string"
        },
        "line3": {
          "title": "Line3",
          "type": "string"
        },
        "city": {
          "title": "City",
          "type": "string"
        },
        "state": {
          "title": "State",
          "type": "string"
        },
        "postalCode": {
          "title": "Postal Code",
          "type": "string"
        },
        "country": {
          "title": "Country",
          "type": "string"
        }
      }
    },

Since this is a nested relation the object is contained within it's parent. However, it does refer to a different resource. Looking at the Discovery Document for Contact, you will find a resource called "AddressInfo" and it's associated methods. You can use this resource to determine how to edit a Contact's address. To change a Contact's "address" property, you could provide a "Address Search" feature that makes a call to the "AddressInfo" "list" method and returns any matching address. You can then take that address object and replace the existing address in the Contact object with it. You would then call the "Contact" "patch" method to update the contact with a different address.

To add a new address that does not already exist to a contact, you could call the "AddressInfo" "insert" method to create the new address and then embed that object into the contact object. However, xTuple's REST API is smart enough to allow you to just build a new "AddressInfo" object, embed it in your contact object and then call the "Contact" "patch" method. The REST API will figure out that the address is a new one and do the insert for you behind the scenes. The address does not have to already exist before you save the contact. The REST API adds new toOne Nested Child objects it finds when you are saving the parent resource.

toMany Nested Child Object:

        "comments": {
          "title": "Comments",
          "type": "array",
          "items": {
            "$ref": "ContactComment"
          }
        },

The toMany Nested Child objects act very similar to the toOne Nested Child objects, but are represented as an array of objects under the property. For example, a Contact resource's "comments" property might look like this:

  "comments": [
    {
      "uuid": "230f6470-3326-491e-b897-9a362e45ac48",
      "commentType": "General",
      "text": "test general comment",
      "created": "2013-07-12T23:13:58.505Z",
      "createdBy": "admin"
    },
    {
      "uuid": "649c83c6-a710-4b0a-9660-32a1f87ca80e",
      "commentType": "General",
      "text": "second comment",
      "created": "2013-07-12T23:14:17.079Z",
      "createdBy": "admin"
    }
  ],

One major difference between toOne Nested Child objects and toMany Nested Child objects is that the toMany Nested JSON-Schema "$ref" reference does not have a related resource that matches it. There is no "ContactComment" resource with a "list" method. You will only find that reference in the JSON-Schema. In this case, when you want to add or edit a "comment" under a "Contact" resource, you do it directly on the parent and then call the "Contact" "patch" method to save it. The JSON-Schema reference is there for you to know what that object should look like when you create it, to build edit forms and validate their data types.

toMany Object Relation:

        "incidentRelations": {
          "title": "Incident Relations",
          "type": "array"
        },