This chapter defines the concept of standard methods, which are List
, Get
, Create
, Update
, and Delete
. Standard methods reduce complexity and
increase consistency. Over 70% of API
methods in the Google APIs
repository are standard methods, which makes them much easier to
learn and use.
The following table describes how to map standard methods to HTTP methods:
Standard Method | HTTP Mapping | HTTP Request Body | HTTP Response Body |
---|---|---|---|
GET <collection URL>
|
N/A | Resource* list | |
GET <resource URL>
|
N/A | Resource* | |
POST <collection URL>
|
Resource | Resource* | |
PUT or PATCH <resource URL>
|
Resource | Resource* | |
DELETE <resource URL>
|
N/A | google.protobuf.Empty
** |
*The resource returned from List
, Get
, Create
, and Update
methods maycontain partial data if the methods support response field
masks, which specify a subset of fields to be returned.
In some cases, the API platform natively supports field masks for all methods.
**The response returned from a Delete
method that doesn't immediately
remove the resource (such as updating a flag or creating a long-running
delete operation) shouldcontain either the long-running operation
or the modified resource.
A standard method mayalso return a long running operation for requests that do not complete within the time-span of the single API call.
The following sections describe each of the standard methods in detail. The examples show the methods defined in .proto files with special annotations for the HTTP mappings. You can find many examples that use standard methods in the Google APIs repository.
List
The List
method takes a collection name and zero or more parameters as
input, and returns a list of resources that match the input.
List
is commonly used to search for resources. List
is suited to data from
a single collection that is bounded in size and not cached. For broader cases,
the custom method
Search
shouldbe used.
A batch get (such as a method that takes multiple resource IDs
and returns an object for each of those IDs) shouldbe implemented as a
custom BatchGet
method, rather than a List
. However, if you have an
already-existing List
method that provides the same functionality,
you mayreuse the List
method for this purpose instead. If you
are using a custom BatchGet
method, it shouldbe mapped to HTTP GET
.
Applicable common patterns: pagination , result ordering .
Applicable naming conventions: filter field , results field
HTTP mapping:
- The
List
method mustuse an HTTPGET
verb. - The request message field(s) receiving the name of the collection whose resources are being listed shouldmap to the URL path. If the collection name maps to the URL path, the last segment of the URL template (the collection ID ) mustbe literal.
- All remaining request message fields shallmap to the URL query parameters.
- There is no request body; the API configuration must notdeclare
a
body
clause. - The response body shouldcontain a list of resources along with optional metadata.
Example:
// Lists books in a shelf.
rpc
ListBooks
(
ListBooksRequest
)
returns
(
ListBooksResponse
)
{
// List method maps to HTTP GET.
option
(
google.api.http
)
=
{
// The `parent` captures the parent resource name, such as "shelves/shelf1".
get
:
" /
v1
/
{
parent
=
shelves
/
*
}
/
books
"
};
}
message
ListBooksRequest
{
// The parent resource name, for example, "shelves/shelf1".
string
parent
=
1
;
// The maximum number of items to return.
int32
page_size
=
2
;
// The next_page_token value returned from a previous List request, if any.
string
page_token
=
3
;
}
message
ListBooksResponse
{
// The field name should match the noun "books" in the method name. There
// will be a maximum number of items returned based on the page_size field
// in the request.
repeated
Book
books
=
1
;
// Token to retrieve the next page of results, or empty if there are no
// more results in the list.
string
next_page_token
=
2
;
}
Get
The Get
method takes a resource name, zero or more parameters, and
returns the specified resource.
HTTP mapping:
- The
Get
method mustuse an HTTPGET
verb. - The request message field(s) receiving the resource name shouldmap to the URL path.
- All remaining request message fields shallmap to the URL query parameters.
- There is no request body; the API configuration must notdeclare
a
body
clause. - The returned resource shallmap to the entire response body.
Example:
// Gets a book.
rpc
GetBook
(
GetBookRequest
)
returns
(
Book
)
{
// Get maps to HTTP GET. Resource name is mapped to the URL. No body.
option
(
google.api.http
)
=
{
// Note the URL template variable which captures the multi-segment resource
// name of the requested book, such as "shelves/shelf1/books/book2
"
get
:
" /
v1
/
{
name
=
shelves
/
*
/
books
/
*
}
"
};
}
message
GetBookRequest
{
// The field will contain name of the resource requested, for example:
// "shelves/shelf1/books/book2
"
string
name
=
1
;
}
Create
The Create
method takes a parent resource name, a resource, and zero or more
parameters. It creates a new resource under the specified parent, and returns
the newly created resource.
If an API supports creating resources, it shouldhave a Create
method for each type of resource that can be created.
HTTP mapping:
- The
Create
method mustuse an HTTPPOST
verb. - The request message shouldhave a field
parent
that specifies the parent resource name where the resource is to be created. - The request message field containing the resource mustmap to
the HTTP request body. If the
google.api.http
annotation is used for theCreate
method, thebody: "<resource_field>"
form mustbe used. - The request maycontain a field named
<resource>_id
to allow callers to select a client assigned id. This field maybe inside the resource. - All remaining request message fields shallmap to the URL query parameters.
- The returned resource shallmap to the entire HTTP response body.
If the Create
method supports client-assigned resource name and
the resource already exists, the request shouldeither fail with error code ALREADY_EXISTS
or
use a different server-assigned resource name and the documentation should be
clear that the created resource name may be different from that passed in.
The Create
method musttake an input resource, so that when the resource
schema changes, there is no need to update both request schema and resource
schema. For resource fields that cannot be set by the clients, they mustbe documented as "Output only" fields.
Example:
// Creates a book in a shelf.
rpc
CreateBook
(
CreateBookRequest
)
returns
(
Book
)
{
// Create maps to HTTP POST. URL path as the collection name.
// HTTP request body contains the resource.
option
(
google.api.http
)
=
{
// The `parent` captures the parent resource name, such as "shelves/1".
post
:
" /
v1
/
{
parent
=
shelves
/
*
}
/
books
"
body
:
" book
"
};
}
message
CreateBookRequest
{
// The parent resource name where the book is to be created.
string
parent
=
1
;
// The book id to use for this book.
string
book_id
=
3
;
// The book resource to create.
// The field name should match the Noun in the method name.
Book
book
=
2
;
}
rpc
CreateShelf
(
CreateShelfRequest
)
returns
(
Shelf
)
{
option
(
google.api.http
)
=
{
post
:
" /
v1
/
shelves
"
body
:
" shelf
"
};
}
message
CreateShelfRequest
{
Shelf
shelf
=
1
;
}
Update
The Update
method takes a request message containing a resource and zero
or more parameters. It updates the specified resource and its properties,
and returns the updated resource.
Mutable resource properties shouldbe mutable by the Update
method, except the properties that contain the resource's name or parent
. Any functionality
to rename
or move
a resource must nothappen in the Update
method
and instead shallbe handled by a custom method.
HTTP mapping:
- The standard
Update
method shouldsupport partial resource update, and use HTTP verbPATCH
with aFieldMask
field namedupdate_mask
. Output fields that are provided by the client as inputs should be ignored. - An
Update
method that requires more advanced patching semantics, such as appending to a repeated field, shouldbe made available by a custom method . - If the
Update
method only supports full resource update, it mustuse HTTP verbPUT
. However, full update is highly discouraged because it has backwards compatibility issues when adding new resource fields. - The message field receiving the resource name mustmap to the URL path. The field maybe in the resource message itself.
- The request message field containing the resource mustmap to the request body.
- All remaining request message fields mustmap to the URL query parameters.
- The response message mustbe the updated resource itself.
If the API accepts client-assigned resource names, the server mayallow
the client to specify a non-existent resource name and create a new resource.
Otherwise, the Update
method shouldfail with non-existent resource name.
The error code NOT_FOUND
shouldbe used if it is the only error condition.
An API with an Update
method that supports resource creation shouldalso provide a Create
method. Rationale is that it is not
clear how to create resources if the Update
method is the only way to
do it.
Example:
// Updates a book.
rpc
UpdateBook
(
UpdateBookRequest
)
returns
(
Book
)
{
// Update maps to HTTP PATCH. Resource name is mapped to a URL path.
// Resource is contained in the HTTP request body.
option
(
google.api.http
)
=
{
// Note the URL template variable which captures the resource name of the
// book to update.
patch
:
" /
v1
/
{
book.name
=
shelves
/
*
/
books
/
*
}
"
body
:
" book
"
};
}
message
UpdateBookRequest
{
// The book resource which replaces the resource on the server.
Book
book
=
1
;
// The update mask applies to the resource. For the `FieldMask` definition,
// see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
FieldMask
update_mask
=
2
;
}
Delete
The Delete
method takes a resource name and zero or more parameters,
and deletes or schedules for deletion the specified resource.
The Delete
method shouldreturn google.protobuf.Empty
.
An API should notrely on any information returned by a Delete
method, as it cannotbe invoked repeatedly.
HTTP mapping:
- The
Delete
method mustuse an HTTPDELETE
verb. - The request message field(s) receiving the resource name shouldmap to the URL path.
- All remaining request message fields shallmap to the URL query parameters.
- There is no request body; the API configuration must notdeclare
a
body
clause. - If the
Delete
method immediately removes the resource, it shouldreturn an empty response. - If the
Delete
method initiates a long-running operation, it shouldreturn the long-running operation. - If the
Delete
method only marks the resource as being deleted, it shouldreturn the updated resource.
Calls to the Delete
method should be idempotent
in
effect, but do not need to yield the same response. Any number of Delete
requests shouldresult in a resource being (eventually) deleted,
but only the first request should result in a success code. Subsequent
requests should result in a google.rpc.Code.NOT_FOUND
.
Example:
// Deletes a book.
rpc
DeleteBook
(
DeleteBookRequest
)
returns
(
google.protobuf.Empty
)
{
// Delete maps to HTTP DELETE. Resource name maps to the URL path.
// There is no request body.
option
(
google.api.http
)
=
{
// Note the URL template variable capturing the multi-segment name of the
// book resource to be deleted, such as "shelves/shelf1/books/book2
"
delete
:
" /
v1
/
{
name
=
shelves
/
*
/
books
/
*
}
"
};
}
message
DeleteBookRequest
{
// The resource name of the book to be deleted, for example:
// "shelves/shelf1/books/book2
"
string
name
=
1
;
}