openapi: 3.0.1 info: title: Dataset Service API description: |- Use the several endpoints provided by The Dataset Service API to manage data usage labels for existing datasets within the Data Lake. Data usage labels are part of Adobe Experience Platform Data Governance, which allows you to manage customer data and ensure compliance with regulations, restrictions, and policies applicable to data use. Dataset Service is separate from Catalog Service, which manages other dataset metadata. - **Related documentation**: - [Data Governance documentation](http://www.adobe.com/go/data-governance-overview-en) - [Catalog Service documentation](http://www.adobe.com/go/data-catalog-service-overview-en) - **Visualize API calls with Postman (a free, third-party software)**: - [Dataset Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Dataset%20Service%20API.postman_collection.json) - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832) - [Steps for importing environments and collections in Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/) - **API paths**: - PLATFORM Gateway URL: https://platform.adobe.io/ - Base path for this API: /data/foundation/dataset - Example of a complete path: https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels - **Required headers**: - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en). - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, "prod"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information. - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`. - **API error handling**: - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors). version: "1.0" servers: - url: //{environment}.adobe.io/data/foundation/dataset variables: environment: default: platform enum: - platform - platform-stage tags: - name: (NEW) Interactive API documentation description: You can now interact with the Experience Platform API endpoints directly from this API reference page. Get your [authentication credentials](https://www.adobe.com/go/platform-api-get-credentials-en) and use the **Try it** functionality in the right rail. Note that by using this functionality, you are making real API calls. Keep this in mind when you interact with production sandboxes. - name: Datasets description: "A dataset is a storage and management construct for a collection of data, typically a table, that contains a schema (columns) and fields (rows). Data usage labels can be applied to entire datasets or individual fields within those datasets in order to enforce usage restrictions." paths: /datasets/{DATASET_ID}/labels: get: tags: - Datasets summary: Retrieve data usage labels for a specific dataset description: |- You can use this endpoint to retrieve data usage labels for a specified dataset. >**NOTE**: See the tutorial on [managing labels for datasets using APIs](https://experienceleague.adobe.com/docs/experience-platform/data-governance/labels/dataset-api.html) for more information on using this endpoint. operationId: retrieveDatasetLabels parameters: - name: DATASET_ID in: path description: "The ID of an existing dataset. Dataset IDs can be retrieved using the [Catalog Service API](https://www.adobe.io/apis/experienceplatform/home/api-reference.html#!acpdr/swagger-specs/catalog.yaml)." required: true schema: type: string - name: Authorization in: header description: "The access token which can be copied from your Experience Platform integration, prefixed with \"Bearer\". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-api-key in: header description: "The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-gw-ims-org-id in: header description: "The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-sandbox-name in: header description: "The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information." required: true schema: type: string responses: "200": description: The data usage labels for the specified dataset were retrieved. x-summary: "Data usage labels retrieved" content: application/json: schema: $ref: '#/components/schemas/LabelPayload' "404": description: "The labels entity was not found. If the dataset indicated in the request path does not have any existing labels applied, this error will occur." x-summary: "Labels entity not found" content: application/json: schema: $ref: '#/components/schemas/NotFoundError' put: tags: - Datasets summary: Update the data usage labels for a specific dataset description: |- You can use this endpoint to update the data usage labels for a specified dataset or fields. >**NOTE**: You can entirely remove a dataset's labels by providing an empty list for the `labels` parameter. It is not mandatory for a dataset to retain any labels. See the tutorial on [managing labels for datasets using APIs](https://experienceleague.adobe.com/docs/experience-platform/data-governance/labels/dataset-api.html) for more information on using this endpoint. operationId: updateDatasetLabels parameters: - name: DATASET_ID in: path description: "The ID of an existing dataset. Dataset IDs can be retrieved using the [Catalog Service API](https://www.adobe.io/apis/experienceplatform/home/api-reference.html#!acpdr/swagger-specs/catalog.yaml)." required: true schema: type: string - name: Authorization in: header description: "The access token which can be copied from your Experience Platform integration, prefixed with \"Bearer\". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-api-key in: header description: "The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-gw-ims-org-id in: header description: "The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-sandbox-name in: header description: "The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information." required: true schema: type: string - name: Content-Type in: header description: The media type being sent in the request payload. The required value for calls to the Dataset Service API is `application/json`. required: true schema: type: string - name: If-Match in: header description: "The version of the dataset entity to compare against. As a requirement for all PUT and DELETE requests for dataset labels, the call will only update the dataset entity if the \"If-Match\" string matches that of the \"etag\" header that is returned in all responses from the Dataset Service API." required: true schema: type: string requestBody: content: '*/*': schema: $ref: '#/components/schemas/LabelPayload' required: false responses: "200": description: The data usage labels were successfully updated. x-summary: "Data usage labels updated" content: application/json: schema: $ref: '#/components/schemas/LabelPayload' "404": description: The labels entity was not found. x-summary: "Labels entity not found" content: application/json: schema: $ref: '#/components/schemas/NotFoundError' "409": description: A data usage policy violation has occurred. x-summary: "Data usage policy violation" content: application/json: schema: $ref: '#/components/schemas/ConflictError' x-codegen-request-body-name: body post: tags: - Datasets summary: Add data usage labels to a specific dataset description: |- This endpoint has been deprecated. You can use this endpoint to add data usage labels to a specified dataset or fields. >**NOTE**: See the tutorial on [managing labels for datasets using APIs](https://experienceleague.adobe.com/docs/experience-platform/data-governance/labels/dataset-api.html) for more information on using this endpoint. operationId: addDatasetLabels parameters: - name: DATASET_ID in: path description: "The ID of an existing dataset. Dataset IDs can be retrieved using the [Catalog Service API](https://www.adobe.io/apis/experienceplatform/home/api-reference.html#!acpdr/swagger-specs/catalog.yaml)." required: true schema: type: string - name: Authorization in: header description: "The access token which can be copied from your Experience Platform integration, prefixed with \"Bearer\". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-api-key in: header description: "The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-gw-ims-org-id in: header description: "The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string - name: x-sandbox-name in: header description: "The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information." required: true schema: type: string - name: Content-Type in: header description: The media type being sent in the request payload. The required value for calls to the Dataset Service API is `application/json`. required: true schema: type: string requestBody: content: '*/*': schema: $ref: '#/components/schemas/LabelPayload' required: false responses: "201": description: The data usage labels were successfully added. x-summary: "Data usage labels added" content: application/json: schema: $ref: '#/components/schemas/LabelPayload' "403": description: The labels entity already exists. Use a PUT request instead. x-summary: "Labels entity already exists" content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' "409": description: A data usage policy violation has occurred. x-summary: "Data usage policy violation" content: application/json: schema: $ref: '#/components/schemas/ConflictError' x-codegen-request-body-name: body deprecated: true components: schemas: LabelPayload: type: object properties: labels: type: array description: A list of data usage labels that have been applied to the dataset as a whole. items: type: string example: "" optionalLabels: type: array description: A list of individual fields within the dataset that have data usage labels applied. items: type: object properties: option: type: object properties: id: type: string description: The URL `$id` of the dataset's schema. example: "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}" contentType: type: string description: The content type and version of the schema. example: application/vnd.adobe.xed-full+json;version=1 schemaPath: type: string description: The path to the specific field in the schema. example: /properties/repositoryCreatedBy description: Describes the field that the labels have been applied to. labels: type: array description: A list of data usage labels that have been applied to the field described in the sibling `option` property. items: type: string example: "" ForbiddenError: allOf: - $ref: '#/components/schemas/NotFoundError' NotFoundError: type: object properties: timestamp: type: string description: A timestamp of when the error occurred. example: 2021-04-21T19:56:46.551Z status: type: string description: The error status. example: NOT_FOUND code: type: string description: The Policy Service error code. example: PES-404 message: type: string description: The error message. example: GET Entities Not Found path: type: string description: "The path used in the lookup attempt, containing the ID of the dataset whose labels were not found." example: /entities/AEP:dataset:60105b5e1af43c18db857d69 ConflictError: type: object properties: code: type: string description: The Policy Service error code. example: PES-409 message: type: string description: The error message. example: Policy conflict error violations: type: array description: A list of policy violations that the attempted action triggered. items: $ref: '#/components/schemas/policyViolation' count: type: number description: The number of policy violations that were triggered. example: 1.0 policyViolation: type: object properties: enforcementRef: type: string description: Indicates the marketing action whose policy constraints were violated. example: /dulepolicy/marketingActions/core/g72cbgy644bsgc3becbba1e197fa25c1e/constraints entities: type: array description: "A list of dataset entities that were involved in the violation, including their associated labels." items: $ref: '#/components/schemas/LabelPayload' violatedPolicies: type: array description: A list of policies that were violated for the datasets and/or fields listed in the `entities` array. items: $ref: '#/components/schemas/violatedPolicy' violatedPolicy: type: object properties: id: type: string description: The policy ID example: corepolicy_0001 name: type: string description: The name of the policy. example: 3rd party export restriction status: type: string description: The current status of the policy. example: ENABLED description: type: string description: A friendly description for the policy. example: Policy for restricting data export to 3rd parties. deny: $ref: '#/components/schemas/policyDeny' policyDeny: type: object properties: label: type: string description: "If only checking against a single label, this property should be used to indicate that label. If multiple labels are being used as part of the expression, then `operator` and `operands` must be used instead." example: C1 operator: type: string description: "When including multiple labels in the expression, this property indicates the relationship the labels have (`AND` or `OR`)." example: AND operands: type: array description: "A list of labels to check for. If `operator` is set to `AND`, all labels must be present for a violation to occur. If `operator` is set to `OR`, only one of the listed labels needs to be present to trigger a violation." items: type: string example: "" imsOrg: type: string description: The ID of the IMS Org that owns the policy. example: "{IMS_ORG}" sandboxName: type: string description: The name of the sandbox that contains the policy. example: prod created: type: number description: A unix timestamp of when the policy was created. example: 1529696681413 createdClient: type: string description: The client that was used to create the policy. example: "{CLIENT_ID}" createdUser: type: string description: The user that created the policy. example: "{USER_ID}" updated: type: number description: A unix timestamp of when the policy was last updated. example: 1529696681413 updatedClient: type: string description: The client that was used to last update the policy. example: "{CLIENT_ID}" updatedUser: type: string description: The user that last updated the policy. example: "{USER_ID}" marketingActionRefs: type: array description: A list of marketing actions that the policy applies to. items: type: string example: "" _links: $ref: '#/components/schemas/_links' description: "An object that describes the specific labels (or combinations therein) that the policy restricts, as well as other metadata." _links: type: object properties: self: type: object properties: href: type: string description: The URL for the currently displayed response page. example: https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5db3393907d49f198b8f0e6a description: Contains the URL for the currently displayed response page. next: type: object properties: href: type: string description: The URL for the next response page. description: Contains the URL for the next response page. page: type: object properties: href: type: string description: The templated URL for viewing other response pages. templated: type: boolean description: Indicates that the sibling `href` property is a template. description: Contains a templated URL for viewing other response pages. description: Contains pagination URLs to view the rest of the response. parameters: x-sandbox-name: name: x-sandbox-name in: header description: "The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information." required: true schema: type: string authorization: name: Authorization in: header description: "The access token which can be copied from your Experience Platform integration, prefixed with \"Bearer\". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string x-gw-ims-org-id: name: x-gw-ims-org-id in: header description: "The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string x-api-key: name: x-api-key in: header description: "The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en)." required: true schema: type: string json-header: name: Content-Type in: header description: The media type being sent in the request payload. The required value for calls to the Dataset Service API is `application/json`. required: true schema: type: string DATASET_ID: name: DATASET_ID in: path description: "The ID of an existing dataset. Dataset IDs can be retrieved using the [Catalog Service API](https://www.adobe.io/apis/experienceplatform/home/api-reference.html#!acpdr/swagger-specs/catalog.yaml)." required: true schema: type: string If-Match: name: If-Match in: header description: "The version of the dataset entity to compare against. As a requirement for all PUT and DELETE requests for dataset labels, the call will only update the dataset entity if the \"If-Match\" string matches that of the \"etag\" header that is returned in all responses from the Dataset Service API." required: true schema: type: string x-original-swagger-version: "2.0"