OCAPI metadata 23.2
The Open Commerce API provides data about itself — metadata. You can obtain API metadata by accessing an own API, the meta API. This API can be accessed like the shop and the data API, but with version 1 as API version. The meta API provides information about
- A list of available APIs
- A list of available versions for an API
- A list of resources and their descriptions
- A list of accessible documents
- A description for a single document
To access the Meta API, you have to send an Authorization: Bearer OAuth token with every request, which is obtained via Account Manager. With the client ID, used to create the access token, the access to all resources via OCAPI settings is proofed and only the available resources and documents are shown. Note that the results may differ, depending on the context used to access the metadata. In the context of a specific site, the OCAPI settings of the site are used to check the access rights for the requesting client and show him only the resources he is allowed to access. The same applies to accessing the metadata in a global context, where the global OCAPI settings are used to retrieve only the metadata the client is allowed to access.
The Meta API responses are cached in the page cache for 24 hours. This means that the cache for the metadata is automatically cleared with page cache clearing.
List of APIs
The following example lists which APIs are available:
REQUEST:
GET /dw/meta/v1/rest HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
"apis": [
{
"link": "https://example.com/s/-/dw/meta/v1/rest/data",
"name": "data"
},
{
"link": "https://example.com/s/-/dw/meta/v1/rest/meta",
"name": "meta"
},
{
"link": "https://example.com/s/-/dw/meta/v1/rest/shop",
"name": "shop"
}]
}List of versions
The following example lists which API versions are available:
REQUEST:
GET /dw/meta/v1/rest/data HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
"versions": [
{
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_2",
"name": "14.2",
"status": "deprecated"
},
{
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_6",
"name": "14.6",
"status": "deprecated"
},
...
{
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_2",
"name": "23.2",
"status": "current"
}
]
}List of resource descriptions
The retrieved document is for using with swagger in version 2.0 and lists all resource paths with their input-parameters and return type descriptions. The following example lists supported resource URIs:
REQUEST:
GET /dw/meta/v1/rest/data/v23_2 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 5981
{
"info":
{
"version": "23.2",
"title": "Data API"
},
"swagger": "2.0",
"basePath": "https://example.com/s/-/dw/data/v23_2",
"paths":
{
"/customer_search":
{
"post":
{
"operationId": "customerSearchcustomer_search",
"responses":
{
"default":
{
"schema":
{
"$ref": "#/definitions/customer_search_result"
}
}
},
"tags": [
"customer_search"
],
"parameters": [
{
"in": "body",
"required": true,
"schema":
{
"$ref": "#/definitions/customer_search_request"
},
"name": "body"
}]
}
},
...
},
"definitions":
{
...,
"customer_search_result":
{
"properties":
{
"count":
{
"format": "int32",
"type": "integer"
},
"hits":
{
"items":
{
"$ref": "customer_search_hit"
},
"type": "array"
},
...
},
"id": "customer_search_result"
},
...
}
}List of documents
The following example lists all available documents for an API in a specific version:
REQUEST:
GET /dw/meta/v1/rest/data/v23_2/documents HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
"data": [
{
"id": "credentials",
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_2/documents/credentials"
},
{
"id": "customer",
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_2/documents/customer"
},
{
"id": "customer_address",
"link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_2/documents/customer_address"
},
...]
}Show document information
The following example shows the metadata for a requested document for an API in a specific version:
REQUEST:
GET /dw/meta/v1/rest/data/v23_2/documents/customer_address_result HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
"properties":
{
"count":
{
"format": "int32",
"type": "integer"
},
"data":
{
"items":
{
"$ref": "https://example.com/s/-/dw/meta/v1/rest/data/v23_2/documents/customer_address"
},
"type": "array"
},
"next":
{
"type": "string"
},
...
}
}
Also it is possible to include the child document definitions by adding a query parameter children=embedded:
REQUEST:
GET /dw/meta/v1/rest/data/v23_2/documents/customer_address_result?children=embedded HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
"properties":
{
"count":
{
"format": "int32",
"type": "integer"
},
"data":
{
"items":
{
"customer_address":
{
"required": [
"address_id",
"country_code",
"last_name"
],
"properties":
{
"address1":
{
"maxLength": 256,
"type": "string"
},
...
}
}
},
"type": "array"
},
...
},
"id": "customer_address_result"
}