Access Metadata
In the May 2016 release, the metadata catalog was enhanced to provide more useful information, such as whether REST resources and their fields are read-only (GET) or writeable (POST and PATCH), and supported query parameters.
Here are some ways to use the metadata catalog:
- How You List the Metadata Catalog
- How You Retrieve Metadata for a Specific Resource
- How You Retrieve Request Syntax for a Resource
How You List the Metadata Catalog
Use the GET method with the following URI to list the metadata catalog:
https://your_site_interface/services/rest/connect/v1.4/metadata-catalogRequesting the metadata catalog returns the list of resources, both standard and custom objects, for example:
{
"items": [
{
"name": "accounts",
"links": [
{
"rel": "alternate",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
"mediaType": "application/schema+json"
},
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
}
]
},
{
"name": "analyticsReports",
"links": [
{
"rel": "alternate",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/analyticsReports",
"mediaType": "application/schema+json"
},
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/analyticsReports",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/analyticsReports"
}
]
},
...
{
"name": "namedIDs",
"links": [
{
"rel": "alternate",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs",
"mediaType": "application/schema+json"
},
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/namedIDs"
}
]
},
{
"name": "queryResults",
"links": [
{
"rel": "alternate",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/queryResults",
"mediaType": "application/schema+json"
},
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/queryResults",
"mediaType": "application/json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/queryResults"
}
]
}
],
"links": [
{
"rel": "canonical",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog"
},
{
"rel": "describedby",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog",
"mediaType": "application/schema+json"
}
]
}How You Retrieve Metadata for a Specific Resource
To retrieve detailed metadata for a resource, use a GET request against its corresponding metadata-catalog resource:
https://your_site_interface/services/rest/connect/version/metadata-catalog/resourcewith the header listed in the following table:
| Header | Value |
|---|---|
Accept |
application/schema+json |
Note:
Because detailed metadata-catalog requests require an Accept header, it's recommended to use a REST client such as Postman or Advanced Rest Client for such requests.Request URI example
For example, to retrieve the metadata for the opportunities resource, use a GET request with the following syntax and an Accept header:
https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accountsResponse body example
Boolean attributes for opportunity fields show the available operations on those fields:
- isAvailableForGET
- isAvailableForPOST
- isAvailableForPATCH
Supported query parameters are listed in the instances links at the end of the response under links.
{
"$schema": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#",
"title": "Resource Schema",
"description": "Schema representing a typed resource",
"type": "object",
"allOf": [
{
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#/definitions/collectionPagedResource"
}
],
"definitions": {
"singularResource": {
"allOf": [
{
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/ConnectOracleRESTStandard#/definitions/resourceMeta"
}
],
"type": "object",
"description": "An account generated for a staff member in the system. Staff accounts are used by CSRs, sales agents, site administrators, etc.",
"name": "accounts",
"isMenu": false,
"releaseIntroduced": "15.5",
"properties": {
"id": {
"description": "Primary key identifier",
"releaseIntroduced": "15.5",
"isDeprecated": false,
"isEnumerable": false,
"label": "ID",
"nullable": false,
"isAvailableForGET": true,
"isAvailableForPOST": false,
"isAvailableForPATCH": false,
"minimum": 1,
"maximum": 9223372036854775807,
"usedAsName": false,
"type": "integer"
},
"lookupName": {
"description": "Name used to lookup this object",
"releaseIntroduced": "15.5",
"isDeprecated": false,
"isEnumerable": false,
"label": "LookupName",
"nullable": false,
"isAvailableForGET": true,
"isAvailableForPOST": false,
"isAvailableForPATCH": false,
"maxLength": 255,
"usedAsName": false,
"type": "string"
},
"createdTime": {
"description": "Creation date and time. Read-only",
"releaseIntroduced": "15.5",
"isDeprecated": false,
"isEnumerable": false,
"label": "CreatedTime",
"nullable": false,
"isAvailableForGET": true,
"isAvailableForPOST": false,
"isAvailableForPATCH": false,
"minimumDateTime": "1970-01-02T00:00:00.000Z",
"maximumDateTime": "2038-01-17T23:59:59.000Z",
"usedAsName": false,
"type": "string"
},
...
"displayName": {
"description": "Display name",
"releaseIntroduced": "15.5",
"isDeprecated": false,
"isEnumerable": false,
"label": "DisplayName",
"nullable": true,
"isAvailableForGET": true,
"isAvailableForPOST": true,
"isAvailableForPATCH": true,
"pattern": "^[^\n]*$",
"minLength": 1,
"maxLength": 80,
"usedAsName": false,
"type": [
"string",
"null"
]
},
...
"staffGroup": {
"description": "Group to which the staff member is assigned",
"releaseIntroduced": "15.5",
"isDeprecated": false,
"isEnumerable": true,
"label": "StaffGroup",
"nullable": false,
"isAvailableForGET": true,
"isAvailableForPOST": true,
"isAvailableForPATCH": true,
"usedAsName": false,
"type": "object",
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/namedIDs/accounts/staffGroup"
}
}
}
},
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"$ref": "#/definitions/singularResource/properties/id"
},
"lookupName": {
"$ref": "#/definitions/singularResource/properties/lookupName"
},
"createdTime": {
"$ref": "#/definitions/singularResource/properties/createdTime"
},
"updatedTime": {
"$ref": "#/definitions/singularResource/properties/updatedTime"
}
}
}
}
},
"links": [
{
"rel": "self",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
"mediaType": "application/schema+json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
},
{
"rel": "search",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"schema": {
"type": "object",
"properties": {
"q": {
"description": "Query parameter that allows searching by providing ROQL WHERE clause filtering",
"type": "string",
"format": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
}
}
}
},
{
"title": "Retrieve collection of accounts",
"rel": "instances",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"mediaType": "application/json;type=collection",
"method": "GET",
"schema": {
"type": "object",
"properties": {
"offset": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/offsetQueryParam"
},
"limit": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/limitQueryParam"
},
"fields": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/fieldsQueryParam"
},
"orderBy": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/orderByQueryParam"
},
"totalResults": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/totalResultsQueryParam"
}
}
}
},
{
"title": "Create an instance of accounts",
"rel": "create",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"method": "POST",
"schema": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts#/definitions/singularResource",
"required": [
"login",
"name",
"profile",
"staffGroup"
]
}
}
]
}How You Retrieve Request Syntax for a Resource
To retrieve the syntax for requests against a resource, use a GET request with the following syntax:
https://your_site_interface/services/rest/connect/version/metadata-catalog/resource#/definitionsNote:
Request syntax isn't available for special resources, such as queryResults, NamedIDs, and NamedIDHierarchies.Request URI example
For example, to retrieve the request syntax for the incidents resource, use the following GET request:
https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts#/definitionsResponse body example
The following are returned:
- Link to ROQL object query syntax
- GET request syntax (if available), as well as links to definitions for supported query parameters
- POST request syntax (if available), as well as parameters and required fields
"type": "object",
"description": "An account generated for a staff member in the system. Staff accounts are used by CSRs, sales agents, site administrators, etc.",
"name": "accounts",
"isMenu": false,
"releaseIntroduced": "15.5",
"links": [
{
"rel": "self",
"href": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts",
"mediaType": "application/schema+json"
},
{
"rel": "describes",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts"
},
{
"rel": "search",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"schema": {
"type": "object",
"properties": {
"q": {
"description": "Query parameter that allows searching by providing ROQL WHERE clause filtering",
"type": "string",
"format": "https://mysite.example.com/services/rest/connect/v1.4/accounts-search-form"
}
}
}
},
{
"title": "Retrieve collection of accounts",
"rel": "instances",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"mediaType": "application/json;type=collection",
"method": "GET",
"schema": {
"type": "object",
"properties": {
"offset": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/offsetQueryParam"
},
"limit": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/limitQueryParam"
},
"fields": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/fieldsQueryParam"
},
"orderBy": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/orderByQueryParam"
},
"totalResults": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/schemas/OracleRESTStandard#/definitions/totalResultsQueryParam"
}
}
}
},
{
"title": "Create an instance of accounts",
"rel": "create",
"href": "https://mysite.example.com/services/rest/connect/v1.4/accounts",
"method": "POST",
"schema": {
"$ref": "https://mysite.example.com/services/rest/connect/v1.4/metadata-catalog/accounts#/definitions/singularResource",
"required": [
"login",
"name",
"profile",
"staffGroup"
]
}
}
]
}