【Architecture】Design - API Design

HTTP REST APIs

URL

Example

The following sections present a few real world examples on how to apply resource-oriented API design to large scale services. You can find more examples in the Google APIs repository.

In these examples, the asterisk indicates one specific resource out of the list.

Gmail API

The Gmail API service implements the Gmail API and exposes most of Gmail functionality. It has the following resource model:

  • API service: 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25

      - A collection of users:```users/*```. Each user has the following resources.
        - A collection of messages: `users/*/messages/*`.
        - A collection of threads: `users/*/threads/*`.
        - A collection of labels: `users/*/labels/*`.
        - A collection of change history: `users/*/history/*`.
        - A resource representing the user profile: `users/*/profile`.
        - A resource representing user settings: `users/*/settings`.

    #### Cloud Pub/Sub API

    The `pubsub.googleapis.com` service implements the [Cloud Pub/Sub API](https://cloud.google.com/pubsub), which defines the following resource model:

    - API service:`pubsub.googleapis.com`

      - A collection of topics: `projects/*/topics/*`.
    - A collection of subscriptions: `projects/*/subscriptions/*`.

    **NOTE:** Other implementations of the Pub/Sub API may choose different resource naming schemes.

    #### Cloud Spanner API

    The `spanner.googleapis.com` service implements the [Cloud Spanner API](https://cloud.google.com/spanner), which defines the following resource model:

    - API service:```spanner.googleapis.com

    • A collection of instances:
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      59
      60
      61
      62
      63
      64
      65
      66
      67
      68
          - A collection of instance operations: `projects/*/instances/*/operations/*`.
          - A collection of databases: `projects/*/instances/*/databases/*`.
          - A collection of database operations: `projects/*/instances/*/databases/*/operations/*`.
          - A collection of database sessions: `projects/*/instances/*/databases/*/sessions/*`.

      <!-- more --> 

      ## Methods

      The following table describes how to map standard methods to HTTP methods:

      | Standard Method                                              | HTTP Mapping    | HTTP Request Body | HTTP Response Body        |
      | :----------------------------------------------------------- | :-------------- | :---------------- | :------------------------ |
      | [`List`](https://cloud.google.com/apis/design/standard_methods#list) | `GET `          | N/A               | Resource* list            |
      | [`Get`](https://cloud.google.com/apis/design/standard_methods#get) | `GET `          | N/A               | Resource*                 |
      | [`Create`](https://cloud.google.com/apis/design/standard_methods#create) | `POST `         | Resource          | Resource*                 |
      | [`Update`](https://cloud.google.com/apis/design/standard_methods#update) | `PUT or PATCH ` | Resource          | Resource*                 |
      | [`Delete`](https://cloud.google.com/apis/design/standard_methods#delete) | `DELETE `       | N/A               | `google.protobuf.Empty`** |

      *The resource returned from `List`, `Get`, `Create`, and `Update` methods **may** contain 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.

      ### 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](https://cloud.google.com/apis/design/custom_methods) `Search` **should** be used.

      A batch get (such as a method that takes multiple resource IDs and returns an object for each of those IDs) **should** be 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 **may** reuse the `List` method for this purpose instead. If you are using a custom `BatchGet` method, it **should** be mapped to `HTTP GET`.

      HTTP mapping:

      - The `List` method **must** use an HTTP `GET` verb.
      - The request message field(s) receiving the name of the collection whose resources are being listed **should** map to the URL path. If the collection name maps to the URL path, the last segment of the URL template (the [collection ID](https://cloud.google.com/apis/design/resource_names#CollectionId)) **must** be literal.
      - All remaining request message fields **shall** map to the URL query parameters.
      - There is no request body; the API configuration **must not** declare a `body` clause.
      - The response body **should** contain a list of resources along with optional metadata.



      ### Get

      The `Get` method takes a resource name, zero or more parameters, and returns the specified resource.

      HTTP mapping:

      - The `Get` method **must** use an HTTP `GET` verb.
      - The request message field(s) receiving the resource name **should** map to the URL path.
      - All remaining request message fields **shall** map to the URL query parameters.
      - There is no request body; the API configuration **must not** declare a `body` clause.
      - The returned resource **shall** map to the entire response body.

      ### Create

      ### Update

      ### Delete



      ### Custom Methods

      Custom methods refer to API methods besides the 5 standard methods. They **should** only be used for functionality that cannot be easily expressed via standard methods. In general, API designers **should** choose standard methods over custom methods whenever feasible. Standard Methods have simpler and well-defined semantics that most developers are familiar with, so they are easier to use and less error prone. Another advantage of standard methods is the API platform has better understanding and support for standard methods, such as billing, error handling, logging, monitoring.

      A custom method can be associated with a resource, a collection, or a service. It **may** take an arbitrary request and return an arbitrary response, and also supports streaming request and response.

      #### URL

      For custom methods, they **should** use the following generic HTTP mapping:

https://service.name/v1/some/resource/name:customVerb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

The reason to use `:` instead of `/` to separate the custom verb from the resource name is to support arbitrary paths. For example, undelete a file can map to `POST /files/a/long/file/name:undelete`



#### Use Cases

Some additional scenarios where custom methods may be the right choice:

- **Reboot a virtual machine.** The design alternatives could be "create a reboot resource in collection of reboots" which feels disproportionately complex, or "virtual machine has a mutable state which the client can update from RUNNING to RESTARTING" which would open questions as to which other state transitions are possible. Moreover, reboot is a well-known concept that can translate well to a custom method which intuitively meets developer expectations.
- **Send mail.** Creating an email message should not necessarily send it (draft). Compared to the design alternative (move a message to an "Outbox" collection) custom method has the advantage of being more discoverable by the API user and models the concept more directly.
- **Promote an employee.** If implemented as a standard `update`, the client would have to replicate the corporate policies governing the promotion process to ensure the promotion happens to the correct level, within the same career ladder etc.





## Standard Fields

This section describes a set of standard message field definitions that should be used when similar concepts are needed. This will ensure the same concept has the same name and semantics across different APIs.

| Name              | Type                                                         | Description                                                  |
| :---------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| `name`            | `string`                                                     | The `name` field should contain the [relative resource name](https://cloud.google.com/apis/design/resource_names#relative_resource_name). |
| `parent`          | `string`                                                     | For resource definitions and List/Create requests, the `parent` field should contain the parent [relative resource name](https://cloud.google.com/apis/design/resource_names#relative_resource_name). |
| `create_time`     | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The creation timestamp of an entity.                         |
| `update_time`     | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The last update timestamp of an entity. Note: update_time is updated when create/patch/delete operation is performed. |
| `delete_time`     | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The deletion timestamp of an entity, only if it supports retention. |
| `expire_time`     | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The expiration timestamp of an entity if it happens to expire. |
| `start_time`      | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The timestamp marking the beginning of some time period.     |
| `end_time`        | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The timestamp marking the end of some time period or operation (regardless of its success). |
| `read_time`       | [`Timestamp`](https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto) | The timestamp at which a particular an entity should be read (if used in a request) or was read (if used in a response). |
| `time_zone`       | `string`                                                     | The time zone name. It should be an [IANA TZ](http://www.iana.org/time-zones) name, such as "America/Los_Angeles". For more information, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. |
| `region_code`     | `string`                                                     | The Unicode country/region code (CLDR) of a location, such as "US" and "419". For more information, see http://www.unicode.org/reports/tr35/#unicode_region_subtag. |
| `language_code`   | `string`                                                     | The BCP-47 language code, such as "en-US" or "sr-Latn". For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. |
| `mime_type`       | `string`                                                     | An IANA published MIME type (also referred to as media type). For more information, see https://www.iana.org/assignments/media-types/media-types.xhtml. |
| `display_name`    | `string`                                                     | The display name of an entity.                               |
| `title`           | `string`                                                     | The official name of an entity, such as company name. It should be treated as the formal version of `display_name`. |
| `description`     | `string`                                                     | One or more paragraphs of text description of an entity.     |
| `filter`          | `string`                                                     | The standard filter parameter for List methods.              |
| `query`           | `string`                                                     | The same as `filter` if being applied to a search method (ie [`:search`](https://cloud.google.com/apis/design/custom_methods#common_custom_methods)) |
| `page_token`      | `string`                                                     | The pagination token in the List request.                    |
| `page_size`       | `int32`                                                      | The pagination size in the List request.                     |
| `total_size`      | `int32`                                                      | The total count of items in the list irrespective of pagination. |
| `next_page_token` | `string`                                                     | The next pagination token in the List response. It should be used as `page_token` for the following request. An empty value means no more result. |
| `order_by`        | `string`                                                     | Specifies the result ordering for List requests.             |
| `request_id`      | `string`                                                     | A unique string id used for detecting duplicated requests.   |
| `resume_token`    | `string`                                                     | An opaque token used for resuming a streaming request.       |
| `labels`          | `map`                                                        | Represents Cloud resource labels.                            |
| `deleted`         | `bool`                                                       | If a resource allows undelete behavior, it must have a `deleted` field indicating the resource is deleted. |
| `show_deleted`    | `bool`                                                       | If a resource allows undelete behavior, the corresponding List method must have a `show_deleted` field so client can discover the deleted resources. |
| `update_mask`     | [`FieldMask`](https://github.com/google/protobuf/blob/master/src/google/protobuf/field_mask.proto) | It is used for `Update` request message for performing partial update on a resource. This mask is relative to the resource, not to the request message. |
| `validate_only`   | `bool`                                                       | If true, it indicates that the given request should only be validated, not executed. |

## Error

If you are a server developer, you should generate errors with enough information to help client developers understand and address the problem. At the same time, you must be aware of the security and privacy of the user data, and avoid disclosing sensitive information in the error message and error details, since errors are often logged and may be accessible by others. For example, an error message like "Client IP address is not on whitelist 128.0.0.0/8" exposes information about the server-side policy, which may not be accessible to the user.

### Error Codes

Google APIs **must** use the canonical error codes defined by [`google.rpc.Code`](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto). Individual APIs **should** avoid defining additional error codes, since developers are very unlikely to write logic to handle a large number of error codes. For reference, handling an average of 3 error codes per API call would mean most application logic would just be for error handling, which would not be a good developer experience.

### Error Messages

The error message should help users **understand and resolve** the API error easily and quickly. In general, consider the following guidelines when writing error messages:

- Do not assume the user is an expert user of your API. Users could be client developers, operations people, IT staff, or end-users of apps.
- Do not assume the user knows anything about your service implementation or is familiar with the context of the errors (such as log analysis).
- When possible, error messages should be constructed such that a technical user (but not necessarily a developer of your API) can respond to the error and correct it.
- Keep the error message brief. If needed, provide a link where a confused reader can ask questions, give feedback, or get more information that doesn't cleanly fit in an error message. Otherwise, use the details field to expand.



## Naming Convertions



## 存疑

要不要保留 HTTP Method Code，比如 404、500，还是用错误码来表示异常情况（此时，所有 REST APIs 都返回 200 的 status code）







# Traditional RPC APIs

## Methods

Only `GET` and `POST` method are allowed. We don't use `PUT` and `DELETE` in project.

`GET` method is used to retrieve information from server, while `POST` requests are generally used to add / update / delete the data on server.

- One notable exception is that, API that pass array to fetch batch data from server could be in `POST` method. This is because it is awkward to pass array of data to server using query string. You can pass array in JSON object in `POST` body. e.g.

Simple request

POST /api/order/get_list

{“orders”:[100001, 100002]}

1
2


Complex request

POST /api/item/get_list

{“items”:[{“shopid”:1000,”itemid”:100001},{“shopid”:1000,”itemid”:100002}]}




# Reference

- https://cloud.google.com/apis/design/

扫一扫，分享到微信