-
Notifications
You must be signed in to change notification settings - Fork 1
REST API: How to discover the schema of a resource
Most REST API resource 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. The Discovery Document for a REST API resource contains a "schemas" object that has a JSON-Schema for each resource and it's children. The "request" and "response" references are refering directly to JSON-Schema object in the "schemas" with a matching property name. For example, the Contact "get" method in the Discovery Document will look similar to this:
...
"get": {
"id": "Contact.get",
"path": "contact/{number}",
"httpMethod": "GET",
"description": "Gets a single Contact record.",
"response": {
"$ref": "Contact"
},
...
},
...When you GET a Contact, you can expect the response returned form the REST API to conform to that JSON-Schema reference:
"$ref": "Contact"
Looking at the "schemas" section of the Discovery Document you can find a matching JSON-Schema that looks like this:
...
"Contact": {
"properties": {
"number": {
"title": "Number",
"isKey": true,
"required": true,
"type": "string"
},
"isActive": {
"title": "Is Active",
"type": "boolean"
},
"honorific": {
"title": "Honorific",
"type": "string"
},
"firstName": {
"title": "First Name",
"type": "string"
},
"middleName": {
"title": "Middle Name",
"type": "string"
},
"lastName": {
"title": "Last Name",
"type": "string"
},
"suffix": {
"title": "Suffix",
"type": "string"
},
"jobTitle": {
"title": "Job Title",
"type": "string"
},
"initials": {
"title": "Initials",
"type": "string"
},
"phone": {
"title": "Phone",
"type": "string"
},
"alternate": {
"title": "Alternate",
"type": "string"
},
"fax": {
"title": "Fax",
"type": "string"
},
"primaryEmail": {
"title": "Primary Email",
"type": "string"
},
"webAddress": {
"title": "Web Address",
"type": "string"
},
"account": {
"title": "Account",
"type": "object",
"$ref": "AccountRelation"
},
"owner": {
"title": "Owner",
"type": "object",
"$ref": "UserAccountRelation"
},
"notes": {
"title": "Notes",
"type": "string"
},
"address": {
"title": "Address",
"type": "object",
"$ref": "AddressInfo"
},
"email": {
"title": "Email",
"type": "object",
"items": {
"$ref": "ContactEmail"
}
},
"comments": {
"title": "Comments",
"type": "object",
"items": {
"$ref": "ContactComment"
}
},
"characteristics": {
"title": "Characteristics",
"type": "object",
"items": {
"$ref": "ContactCharacteristic"
}
},
"accounts": {
"title": "Accounts",
"type": "object",
"items": {
"$ref": "ContactAccount"
}
},
"contacts": {
"title": "Contacts",
"type": "object",
"items": {
"$ref": "ContactContact"
}
},
"items": {
"title": "Items",
"type": "object",
"items": {
"$ref": "ContactItem"
}
},
"files": {
"title": "Files",
"type": "object",
"items": {
"$ref": "ContactFile"
}
},
"urls": {
"title": "Urls",
"type": "object",
"items": {
"$ref": "ContactUrl"
}
},
"incidents": {
"title": "Incidents",
"type": "object",
"items": {
"$ref": "ContactIncident"
}
},
"opportunities": {
"title": "Opportunities",
"type": "object",
"items": {
"$ref": "ContactOpportunity"
}
},
"toDos": {
"title": "To Dos",
"type": "object",
"items": {
"$ref": "ContactToDo"
}
},
"incidentRelations": {
"title": "Incident Relations",
"type": "array",
"items": {
"$ref": "IncidentRelation/number"
}
},
"opportunityRelations": {
"title": "Opportunity Relations",
"type": "array",
"items": {
"$ref": "OpportunityRelation/number"
}
},
"toDoRelations": {
"title": "To Do Relations",
"type": "array",
"items": {
"$ref": "ToDoRelation/uuid"
}
},
"projects": {
"title": "Projects",
"type": "object",
"items": {
"$ref": "ContactProject"
}
},
"projectRelations": {
"title": "Project Relations",
"type": "array",
"items": {
"$ref": "ProjectRelation/number"
}
},
"customers": {
"title": "Customers",
"type": "object",
"items": {
"$ref": "ContactCustomer"
}
}
}
},
...The JSON-Schema tells you what each of the properties are in the JSON object that will be returned by the REST API. It contains the name of the property, a "title" that describes it in a human readable format and what the data type is. Depending on the property and it's type, there may be more information about the property including:
- If it is required:
"required": true,
- If it is the identifier key of the resource that you would use in the URL to access it or to link it to another resource:
"isKey": true,
- Some data types further define their length and format:
"type": "integer",
"format": "int32",
"minimum": "-2147483648",
"maximum": "2147483647"
Notice that the JSON-Schema for Contact has "$ref" references within it. There are four 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"
},
- toOne Object Key Relation:
"salesRep": {
"title": "Sales Rep",
"type": "string",
"$ref": "SalesRep/number"
},
- toMany Nested Child Object:
"comments": {
"title": "Comments",
"type": "array",
"items": {
"$ref": "ContactComment"
}
},
- toMany Object Key Relation:
"incidentRelations": {
"title": "Incident Relations",
"type": "array",
"items": {
"$ref": "IncidentRelation/number"
}
},
Refer to the How to discover a resource's relations to other objects documentation to learn more about how to work with these relations.
Below is an example of a Contact GET request response. Review the Contact JSON-Schema above and compare it to the response below. Note how the different data types are reflected and how the different types of child relations look.
{
"number": "1",
"isActive": true,
"honorific": "Mr",
"firstName": "Mike",
"middleName": "",
"lastName": "Farley",
"suffix": "",
"jobTitle": "",
"initials": "",
"phone": "703-931-4269",
"alternate": "",
"fax": "703-931-2212",
"primaryEmail": "[email protected]",
"webAddress": "",
"account": {
"number": "TTOYS",
"name": "Tremendous Toys Incorporated",
"isActive": true,
"owner": {
"username": "admin",
"propername": "Administrator",
"isActive": true,
"disableExport": false,
"email": "insert email here"
}
},
"owner": {
"username": "admin",
"propername": "Administrator",
"isActive": true,
"disableExport": false,
"email": "insert email here"
},
"notes": "",
"address": {
"number": "1",
"isActive": true,
"line1": "Tremendous Toys Inc.",
"line2": "101 Toys Place",
"line3": "",
"city": "Walnut Hills",
"state": "VA",
"postalCode": "22209",
"country": "United States"
},
"email": [
{
"uuid": "01c22285-afc5-4cd6-cbda-e80fff250013",
"email": "[email protected]"
}
],
"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"
}
],
"characteristics": [],
"accounts": [],
"contacts": [],
"items": [],
"files": [],
"urls": [],
"incidents": [],
"opportunities": [],
"toDos": [],
"incidentRelations": [
"15002",
"15005"
],
"opportunityRelations": [],
"toDoRelations": [
"cfd895e2-4ae4-4e67-d2dc-01605456079a"
],
"projects": [],
"projectRelations": [],
"customers": []
}