Commit c36ff937 authored by StephenWhitley's avatar StephenWhitley
Browse files

Update Documentation reposityory - adding example API documentation and tutorials

parent 63135016
This diff is collapsed.
This diff is collapsed.
swagger: '2.0'
info:
description: "APIs to help ensure compliance with legal data governance when dealing with data in the Data Ecosystem."
version: 1.0.0
title: Legal data governance APIs
contact:
name: DELFI support
email: DELFI-DevPortal-Help@slb.com
host: "api.evq.csp.slb.com"
basePath: "/de/legal/v1"
tags:
- name: LegalTag
description: ''
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- bearer: []
appkey: []
paths:
'/legaltags:batchRetrieve':
post:
tags:
- LegalTag
summary: Get the Legaltags
description: "This allows for the retrieval of your LegalTags using the name associated with it. A maximum of 25 can be retrieved at once. Allowed roles: users.datalake.viewers, users.datalake.editors, users.datalake.admins"
operationId: Get the Legaltags
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/RequestLegalTags'
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Retrieved LegalTags successfully.
schema:
$ref: '#/definitions/LegalTagDtos'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
'404':
description: One or more requested LegalTags were not found.
security:
- bearer: []
appkey: []
'/legaltags/{name}':
get:
tags:
- LegalTag
summary: Gets a Legaltag
description: "This allows for the retrieval of your LegalTag using the name associated with it. Allowed roles: users.datalake.viewers, users.datalake.editors, users.datalake.admins"
operationId: Gets a Legaltag
consumes:
- application/json
produces:
- application/json
parameters:
- name: name
in: path
required: true
type: string
x-example: Slb-Private-USA-EHC
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Retrieved LegalTag successfully.
schema:
$ref: '#/definitions/LegalTagDto'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
'404':
description: Requested LegalTag was not found.
security:
- bearer: []
appkey: []
'/legaltags':
get:
tags:
- LegalTag
summary: List the Legaltags
description: "This allows for the retrieval of all LegalTags. You can specify parameters to choose what subset of LegalTags you want to list. Allowed roles: users.datalake.viewers, users.datalake.editors, users.datalake.admins"
operationId: List the Legaltags
consumes:
- application/json
produces:
- application/json
parameters:
- name: valid
in: query
description: >-
If true returns only valid LegalTags, if false returns only invalid
LegalTags. Default value is true.
required: false
type: boolean
default: true
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Retrieved LegalTags successfully.
schema:
$ref: '#/definitions/LegalTagDtos'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
security:
- bearer: []
appkey: []
post:
tags:
- LegalTag
summary: Create a LegalTag
description: "This allows for the creation of your LegalTag. A LegalTag is uniquely identified by its name. A LegalTag must be created before you can start ingesting data and the correct LegaltTag should be assigned to that data. Allowed roles: users.datalake.editors, users.datalake.admins"
operationId: Create a LegalTag
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/LegalTagDto'
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'201':
description: Created LegalTag successfully.
schema:
$ref: '#/definitions/LegalTagDto'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
'409':
description: A LegalTag with the given name already exists.
security:
- bearer: []
appkey: []
put:
tags:
- LegalTag
summary: Update a Legaltag
description: "This allows to update certain properties of your LegalTag using the name associated with it. Allowed roles: users.datalake.admins"
operationId: Update a Legaltag
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/UpdateLegalTag'
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Updated LegalTag successfully.
schema:
$ref: '#/definitions/LegalTagDto'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
'404':
description: Requested LegalTag to update was not found.
security:
- bearer: []
appkey: []
'/legaltags:validate':
post:
tags:
- LegalTag
summary: Validate the Legaltags
description: "This allows you to send the names of the LegalTags you want to validate. It will return any which are invalid and the reason they are. A maximum of 25 can be retrieved at once. Allowed roles: users.datalake.viewers, users.datalake.editors, users.datalake.admins"
operationId: Validate the Legaltags
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/RequestLegalTags'
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Retrieved LegalTag names with reason successfully.
schema:
$ref: '#/definitions/InvalidTagsWithReason'
'400':
description: Invalid parameters were given on request.
'401':
description: You do not have permissions to access this API.
security:
- bearer: []
appkey: []
'/legaltags:properties':
get:
tags:
- LegalTag
summary: Get the allowed Legaltag values
description: "This allows for the retrieval of the allowed values for the given data partition for LegalTag properties when creating a LegalTag. Allowed roles: users.datalake.viewers, users.datalake.editors, users.datalake.admins"
operationId: Get the allowed Legaltag values
consumes:
- application/json
produces:
- application/json
parameters:
- name: slb-data-partition-id
in: header
description: >-
This value should be the desired data partition id.
required: true
type: string
default: common
responses:
'200':
description: Retrieved properties successfully.
schema:
$ref: '#/definitions/ReadablePropertyValues'
'401':
description: You do not have permissions to access this API.
security:
- bearer: []
appkey: []
securityDefinitions:
bearer:
type: apiKey
name: Authorization
in: header
appkey:
type: apiKey
name: appkey
in: header
definitions:
LegalTagDto:
type: object
properties:
name:
type: string
example: Slb-Private-EHCData
description: The name of the LegalTag.
description:
type: string
description: The description of the LegalTag.
properties:
$ref: '#/definitions/Properties'
description: Represents a single LegalTag.
example:
name: public-usa-dataset-1
description: A legaltag used for demonstration purposes.
properties:
countryOfOrigin:
- US
contractId: No Contract Related
expirationDate: '2099-01-01'
originator: SLB
dataType: Public Domain Data
securityClassification: Public
personalData: No Personal Data
exportClassification: Not - Technical Data
LegalTagDtos:
type: object
properties:
legalTags:
type: array
description: A collection of complete LegalTags
items:
$ref: '#/definitions/LegalTagDto'
description: Represents a collection of LegalTags.
Properties:
type: object
required:
- contractId
- countryOfOrigin
- dataType
- exportClassification
- originator
- personalData
- securityClassification
properties:
countryOfOrigin:
type: array
example: US
description: The ISO Alpha 2 country code(s) of where the data relates to.
items:
type: string
contractId:
type: string
example: No Contract Related
description: >-
The Id of the physical contract associated with the data being
ingested.
expirationDate:
type: string
example: '2025-12-25'
description: The optional expiration date of the contract in the format YYYY-MM-DD
originator:
type: string
example: Schlumberger
description: The company who owns the data.
dataType:
type: string
example: Third Party Data
description: The type of data being ingested.
securityClassification:
type: string
example: Private
description: The security classification of the data.
personalData:
type: string
example: No Personal Data
description: Whether the data contains any personally identifiable data.
exportClassification:
type: string
example: EAR99
description: The ECCN value of the data if one applies.
description: LegalTag properties
RequestLegalTags:
type: object
required:
- names
properties:
names:
type: array
description: The name of all the LegalTags to retrieve.
items:
type: string
maxItems: 25
minItems: 1
description: The model to retrieve multiple LegalTags in batch.
example:
names:
- common-public-usa-dataset-1
UpdateLegalTag:
type: object
required:
- contractId
- name
properties:
name:
type: string
description: The name of the LegalTag.
contractId:
type: string
example: No Contract Related
description: >-
The Id of the physical contract associated with the data being
ingested.
description:
type: string
description: >-
The optional description if the LegalTag to allow for easier
discoverability of Legaltags overtime.
expirationDate:
type: string
example: '2025-12-25'
description: The optional expiration date of the contract in the format YYYY-MM-DD
description: The model to update an existing LegalTag
example:
name: common-public-usa-mydataset-1
contractId: abc123
description: An update on the demonstration Legaltag
expirationDate: '2099-01-01'
InvalidTagWithReason:
type: object
properties:
name:
type: string
description: The name of the LegalTag.
reason:
type: string
description: The reason the LegalTag is currently invalid.
description: Represents a single invalid LegalTag.
InvalidTagsWithReason:
type: object
properties:
invalidLegalTags:
type: array
description: A collection of invalid LegalTags.
items:
$ref: '#/definitions/InvalidTagWithReason'
description: Represents a collection invalid LegalTags.
ReadablePropertyValues:
type: object
properties:
countriesOfOrigin:
type: object
description: >-
The values of all the allowed Countries of Origin with the ISO Alpha 2
code and country name.
additionalProperties:
type: string
otherRelevantDataCountries:
type: object
description: >-
The values of all the allowed Other Relevant Data Countries with the
ISO Alpha 2 code and country name.
additionalProperties:
type: string
securityClassifications:
type: array
description: The values of all the allowed Security Classifications.
uniqueItems: true
items:
type: string
exportClassificationControlNumbers:
type: array
description: The name of all the allowed Export Classifications.
uniqueItems: true
items:
type: string
personalDataTypes:
type: array
description: The name of all the allowed Personal Data Type values.
uniqueItems: true
items:
type: string
dataTypes:
type: array
description: The name of all the allowed Data Type values.
uniqueItems: true
items:
type: string
description: Shows the allowed values of the fields of a LegalTag.
This diff is collapsed.
{
"swagger": "2.0",
"info": {
"version": "1.0.1.10",
"title": "Document Query Service",
"description": "Endpoints to search through the document data (unstructured data)"
},
"host": "document-query-dot-evt-ddl-us-services.appspot.com",
"basePath": "/_ah/api",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/unstructuredQuery/v1/document": {
"get": {
"description": "Searches through a document archive and returns ranked results with document meta information. This service also support filter query for the various attributes. Filters shall be placed after query string followed by semi-colon. \\n List of attributes supported by the service for filters are:\\n - filetype (case sensitive), \\n - wellbore (case sensitive), \\n - title (case sensitive), \\n - wellname (case sensitive), \\n - subtype (case sensitive), \\n - author (case sensitive), \\\\n - report (case sensitive), \\n - classes (case insensitive), \\n - classification (case insensitive), \\n - keywords(case insensitive),\\n - category (case insensitive) \\n - size, \\n - latitude, \\n - longitude",
"operationId": "UnstructuredQueryGetDocuments",
"parameters": [
{
"name": "query",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "limit",
"in": "query",
"required": false,
"type": "integer",
"format": "int32"
},
{
"name": "offset",
"in": "query",
"required": false,
"type": "integer",
"format": "int32"
},
{
"name": "responseFields",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/PaginatedList_Document"
}
}
},
"security" : [
{
"Bearer" : [ ]
},
{
"google_id_token" : [ ]
},
{
"sauth_id_token" : [ ]
}
],
"tags": [
"discovery_unstructured_query_service"
]
}
},
"/unstructuredQuery/v1/document/{id}": {
"get": {
"description": "Returns a document meta information of the particular document id.",
"operationId": "UnstructuredQueryGetDocument",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "responseFields",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "A successful response",
"schema": {
"$ref": "#/definitions/Document"
}
}
},
"security" : [
{
"Bearer" : [ ]
},
{
"google_id_token" : [ ]
},
{
"sauth_id_token" : [ ]
}
],
"tags": [
"discovery_unstructured_query_service"
]
}
},
"/unstructuredQuery/v1/document/{id}/page": {
"get": {
"description": "Searches for the specified keyword, if passed, through all the pages for a specified document and returns the pages that match the query criteria.",
"operationId": "UnstructuredQueryGetPages",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "query",
"in": "query",
"required": false,
"type": "string"
},
{
"name": "limit",
"in": "query",
"required": false,
"type": "integer",
"format": "int32"
},
{
"name": "offset",
"in": "query",
"required": false,