API Overview

To enable programmatic control over its objects, the Google Cloud Platform supports a range of REST API endpoints across the objects in the platform. This section provides an overview of the API design, methods, and supported use cases.

Design Overview

URL Format

<http/https>://<my_server>:<port_number>/<version>/<endpoint>/[resource_id]/[association][?args]

Elements in square brackets [brackets] are optional.

ElementDescriptionExample
<http/https>

HTTP protocol identifier. The protocol should be https in a production environment.

https
<my_server>

Name of the Google Cloud node

myapp.example.com
<port_number>

Port number over which you access the Google Cloud Platform. By default, this value is 3005.

3005
<version>

API version number.

NOTE: Unless stated otherwise, the versions for all API endpoints is v4.

v4
<endpoint>Name of the API endpoint to use./connections
[resource_id]Internal identifier for the specific resource requested from the endpoint. This value defines the object against which the requested operation is performed./10
[association]

If applicable, the association identifiers the API endpoint that is requested using the context determined by the <endpoint> and the [resource_id].

Associations can also be referenced by query parameter. See Embedding Associations below.

/jobGroups
[?args]In some cases, arguments can be passed to the endpoint in the form of query parameters.?arg1=value1&arg2=value2

Naming Conventions

  • Resource names are plural and expressed in camelCase.
  • Resource names are consistent between main URL and URL parameter.

v4 conventions

The following conventions apply to v4 and later versions of the APIs:

  • Parameter lists are consistently enveloped in the following manner:

    { "data": [
        {
          ...
        }
      ]
    }
  • Field names are in camelCase and are consistent with the resource name in the URL or with the embed URL parameter.

Embedding Associations

An association can be referenced using the above URL structuring or by applying the embed query parameter as part of the reference to the specific resource. In the following example, the sub-jobs of a jobGroup are embedded in the response for jobGroup=1:

https:/myapp.example.com/v4/jobGroups/1?embed=jobs

Example response:

{
    "id": 1,
    "name": null,
    "description": null,
    "ranfrom": "ui",
    "ranfor": "recipe",
    "status": "Complete",
    "profilingEnabled": true,
    "runParameterReferenceDate": "2019-04-23T17:00:56.000Z",
    "createdAt": "2019-04-23T17:00:56.728Z",
    "updatedAt": "2019-04-23T17:01:03.084Z",
    "jobs": {
        "data": [
            {
                "id": 1,
                "executionLanguage": "photon",
                "cpJobId": null,
                "templateLocation": null,
                "createdAt": "2019-04-23T17:00:56.952Z",
                "updatedAt": "2019-04-23T17:01:00.670Z",
                "status": "Complete",
                "jobType": "wrangle",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:00:58.589Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "wrangleScript": null,
                "emrcluster": null
            },
            {
                "id": 2,
                "createdAt": "2019-04-23T17:00:57.034Z",
                "updatedAt": "2019-04-23T17:01:02.642Z",
                "status": "Complete",
                "jobType": "filewriter",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:01:00.922Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "scriptResult": {
                    "id": 1
                },
                "writeSetting": {
                    "id": 2
                }
            },
            {
                "id": 3,
                "createdAt": "2019-04-23T17:00:57.037Z",
                "updatedAt": "2019-04-23T17:01:03.077Z",
                "status": "Complete",
                "jobType": "filewriter",
                "sampleSize": 100,
                "percentComplete": 100,
                "lastHeartbeatAt": "2019-04-23T17:01:00.843Z",
                "creator": {
                    "id": 1
                },
                "jobGroup": {
                    "id": 1
                },
                "errorMessage": null,
                "scriptResult": {
                    "id": 2
                },
                "writeSetting": {
                    "id": 1
                }
            }
        ]
    },
    "workspace": {
        "id": 1
    },
    "creator": {
        "id": 1
    },
    "updater": {
        "id": 1
    },
    "snapshot": {
        "id": 8
    },
    "wrangledDataset": {
        "id": 7
    },
    "flowRun": null
}

The id value of the association is always included in the response.

Media Type Headers

NOTE: Some endpoints may accept and return a custom media type. These endpoints are documented.

ActionHeaderRequired?
Client request that expects a response bodyrequest header:
Accept: application/json
should include
Client request that includes a request bodyrequest header:
Content-Type: application/json
required
Server response that includes a response bodyresponse header:
Content-Type: application/json
required

Authentication

Each call to an API endpoint must include authentication credentials for a user with access to the requested objects. See API Authentication.

HTTP Status Codes and Errors

Request MethodRequest EndpointHTTP Status Code (success)
POST/v4/<resource>201 Created
GET/v4/<resource>200 OK
GET/v4/<resource>/<id>

304 Not Modified when client has cached version.

See Caching below.

PATCH/v4/<resource>/<id>200 OK
PUT/v4/<resource>/<id>200 OK
DELETE/v4/<resource>/<id>204 No Content

The following error codes can apply to any of the above requests:

NOTE: 5xx status codes may be generated by the server.

HTTP Status Code (client errors)Notes
400 Bad Request

Potential reasons:

  • Resource doesn't exist.
  • Request is incorrectly formatted.
  • Request contains invalid values.
403 ForbiddenIncorrect permissions to access the Resource.
404 Not FoundResource cannot be found.
410 GoneResource has been previously deleted.
415 Unsupported Media TypeIncorrect Accept header.

Caching

When a resource has been cached in the client, the client may set an If-Modified-Since header in HTTP date format on the request. If so:

General ResponseHTTP Status Code
Returns full modified resource200 OK
Returns an empty response for unmodified resource304 Not Modified

About This Documentation

Applicable API versions

Unless otherwise noted, the documentation and examples apply to latest version of the Google Cloud Platform APIs.

API examples

Examples may require modification to work in your environment.

NOTE: Some examples may not be reflective of your environment. Examples may contain references to examples or features not supported in your environment.

Var denne siden nyttig? Si fra hva du synes:

Send tilbakemelding om ...

Google Cloud Dataprep Documentation
Trenger du hjelp? Gå til brukerstøttesiden vår.