Using the API

Conventions

Names, standard methods, pagination, field masks, etags and request ids.

Plany follows the Google API Improvement Proposals. If you have used a googleapis-shaped API, none of this will surprise you.

Resource names

One string identifies a resource and encodes its whole hierarchy. There are no separate id parameters. See Resource names for every pattern.

projects/{project}/locations/{location}/gameServers/{game_server}

Standard methods

Method	Takes	Returns
`Get<Resource>`	`name`	the resource
`List<Resource>s`	`parent`, `page_size`, `page_token`, and sometimes `filter`	a page and `next_page_token`
`Create<Resource>`	`parent`, the resource, `<resource>_id`, `request_id`	the resource, or an operation
`Update<Resource>`	the resource, `update_mask`	the resource, or an operation
`Delete<Resource>`	`name`	`Empty`, or an operation

Pagination

Ask for a page, then pass next_page_token back to get the next one. An empty next_page_token means you have the last page.

grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
  -d '{"parent": "projects//locations/", "page_size": 100, "page_token": "'"$NEXT"'"}' \
  api.plany.cloud:443 plany.playpute.v1.PlayputeService/ListGameServers

Treat a page token as opaque: pass back exactly what you were given.

Field masks

An update changes only the fields named in update_mask, so you can send a partial resource without clearing everything you left out.

1grpcurl -H "authorization: Bearer $PLANY_API_KEY" \
2  -d '{
3    "game_server": {
4      "name": "projects//locations//gameServers/",
5      "sleep_after_idle": "1800s"
6    },
7    "update_mask": "sleepAfterIdle"
8  }' \
9  api.plany.cloud:443 plany.playpute.v1.PlayputeService/UpdateGameServer

A field in the mask is replaced wholesale, not merged. Naming a map or a message in update_mask replaces the whole of it with what you sent. To change one entry of a map such as settings, read the resource, change the entry, and send the whole map back.

Etags

Most resources carry an etag. Send it back on an update or a delete and the write is refused with ABORTED if the resource changed since you read it, rather than overwriting somebody else's change. Leave it out and the last write wins.

Request ids

Most create calls accept a request_id. Retry with the same one and you get the original result back rather than a second resource — which is what makes a retry after a timeout safe.

Wildcards

Some List calls accept - in place of a parent's id — projects/- — to list across every project you can see. The reference says which; elsewhere, name one project.

Money

google.type.Money: currency_code, units and nanos. Use integer arithmetic when you add amounts up, never floating point.

Time

google.protobuf.Timestamp for instants, google.protobuf.Duration for spans, and google.type.Interval for ranges such as a billing period.

Field behaviour

Every field in the schema is annotated, and the annotations mean what they say:

Annotation	Means
`REQUIRED`	Must be set.
`OPTIONAL`	May be omitted.
`OUTPUT_ONLY`	Set by Plany; ignored on input.
`INPUT_ONLY`	Accepted and never returned, such as a build's Steam password.
`IMMUTABLE`	Settable at create and not afterwards.
`IDENTIFIER`	The resource name.

An INPUT_ONLY value is stored encrypted and never returned by any call, so you cannot read one back to check it. Keep your own copy.