finished Chapter 3.

kcyeu · Dec 5, 2014 · 6292338 · 6292338
1 parent a6d6d22
commit 6292338
Show file tree

Hide file tree

Showing 7 changed files with 28 additions and 169 deletions.
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -1,8 +1,8 @@
 ## 貢獻者
 
-* Wesley Beary <geemus+github@gmail.com>
-* Mark McGranaghan <mmcgrana@gmail.com>
-* Jamu Kakar <jkakar@kakar.ca>
-* Jonathan Roes <jroes@jroes.net>
-* Kuo-Cheng Yeu <kmd@mikuru.tw>
+* [Wesley Beary](mailto:geemus+github@gmail.com)
+* [Mark McGranaghan](mailto:mmcgrana@gmail.com)
+* [Jamu Kakar](mailto:jkakar@kakar.ca)
+* [Jonathan Roes](mailto:jroes@jroes.net)
+* [Kuo-Cheng Yeu](https://github.com/kcyeu)
 
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -10,10 +10,10 @@
 * [需求](requests/README.md)
   *  [回傳適當的狀態碼](requests/return-appropriate-status-codes.md)
   *  [情況許可時提供全部資源](requests/provide-full-resources-where-available.md)
-  *  [Accept serialized JSON in request bodies](requests/accept-serialized-json-in-request-bodies.md)
+  *  [接受需求本體的序列化 JSON](requests/accept-serialized-json-in-request-bodies.md)
   *  [使用一致的路徑格式](requests/use-consistent-path-formats.md)
   *  [小寫路徑與屬性](requests/downcase-paths-and-attributes.md)
-  *  [Support non-id dereferencing for convenience](requests/support-non-id-dereferencing-for-convenience.md)
+  *  [支援非 ID 的便利存取](requests/support-non-id-dereferencing-for-convenience.md)
   *  [減少巢狀路徑](requests/minimize-path-nesting.md)
 * [回應](responses/README.md)
   *  [Provide resource (UU)IDs](responses/provide-resource-uuids.md)

diff --git a/artifacts/README.md b/artifacts/README.md
@@ -1,6 +1,6 @@
 ### 產物
 
- *  [提供機器可讀的 JSON 大綱](artifacts/provide-machine-readable-json-schema.md)
- *  [提供一般人可讀的文件](artifacts/provide-human-readable-docs.md)
- *  [提供執行範例](artifacts/provide-executable-examples.md)
- *  [描述穩定性](artifacts/describe-stability.md)
+  *  [提供機器可讀的 JSON 大綱](artifacts/provide-machine-readable-json-schema.md)
+  *  [提供一般人可讀的文件](artifacts/provide-human-readable-docs.md)
+  *  [提供執行範例](artifacts/provide-executable-examples.md)
+  *  [描述穩定性](artifacts/describe-stability.md)
diff --git a/foundations/README.md b/foundations/README.md
@@ -1,8 +1,8 @@
 ### 基礎
 
- *  [要求使用 TLS](foundations/require-tls.md)
- *  [以 Accept 標頭做版本控管](foundations/version-with-accepts-header.md)
- *  [以 ETag 支援快取](foundations/support-caching-with-etags.md)
- *  [以 Request-Id 追蹤需求](foundations/trace-requests-with-request-ids.md)
- *  [以 Range 分頁](foundations/paginate-with-ranges.md)
+  *  [要求使用 TLS](foundations/require-tls.md)
+  *  [以 Accept 標頭做版本控管](foundations/version-with-accepts-header.md)
+  *  [以 ETag 支援快取](foundations/support-caching-with-etags.md)
+  *  [以 Request-Id 追蹤需求](foundations/trace-requests-with-request-ids.md)
+  *  [以 Range 分頁](foundations/paginate-with-ranges.md)
 
diff --git a/requests/README.md b/requests/README.md
@@ -1,2 +1,9 @@
 ### 需求
 
+  *  [回傳適當的狀態碼](requests/return-appropriate-status-codes.md)
+  *  [情況許可時提供全部資源](requests/provide-full-resources-where-available.md)
+  *  [接受需求本體的序列化 JSON](requests/accept-serialized-json-in-request-bodies.md)
+  *  [使用一致的路徑格式](requests/use-consistent-path-formats.md)
+  *  [小寫路徑與屬性](requests/downcase-paths-and-attributes.md)
+  *  [支援非 ID 的便利存取](requests/support-non-id-dereferencing-for-convenience.md)
+  *  [減少巢狀路徑](requests/minimize-path-nesting.md)
diff --git a/requests/accept-serialized-json-in-request-bodies.md b/requests/accept-serialized-json-in-request-bodies.md
@@ -1,76 +1,6 @@
-### Requests
-
-#### Return appropriate status codes
-
-Return appropriate HTTP status codes with each response. Successful
-responses should be coded according to this guide:
-
-* `200`: Request succeeded for a `GET` call, for a `DELETE` or
-  `PATCH` call that completed synchronously, or for a `PUT` call that
-  synchronously updated an existing resource
-* `201`: Request succeeded for a `POST` call that completed
-  synchronously, or for a `PUT` call that synchronously created a new
-  resource
-* `202`: Request accepted for a `POST`, `PUT`, `DELETE`, or `PATCH` call that
-  will be processed asynchronously
-* `206`: Request succeeded on `GET`, but only a partial response
-  returned: see [above on ranges](#paginate-with-ranges)
-
-Pay attention to the use of authentication and authorization error codes:
-
-* `401 Unauthorized`: Request failed because user is not authenticated
-* `403 Forbidden`: Request failed because user does not have authorization to access a specific resource
-
-Return suitable codes to provide additional information when there are errors:
-
-* `422 Unprocessable Entity`: Your request was understood, but contained invalid parameters
-* `429 Too Many Requests`: You have been rate-limited, retry later
-* `500 Internal Server Error`: Something went wrong on the server, check status site and/or report the issue
-
-Refer to the [HTTP response code spec](https://tools.ietf.org/html/rfc7231#section-6)
-for guidance on status codes for user error and server error cases.
-
-#### Provide full resources where available
-
-Provide the full resource representation (i.e. the object with all
-attributes) whenever possible in the response. Always provide the full
-resource on 200 and 201 responses, including `PUT`/`PATCH` and `DELETE`
-requests, e.g.:
-
-```bash
-$ curl -X DELETE \  
-  https://service.com/apps/1f9b/domains/0fd4
-
-HTTP/1.1 200 OK
-Content-Type: application/json;charset=utf-8
-...
-{
-  "created_at": "2012-01-01T12:00:00Z",
-  "hostname": "subdomain.example.com",
-  "id": "01234567-89ab-cdef-0123-456789abcdef",
-  "updated_at": "2012-01-01T12:00:00Z"
-}
-```
-
-202 responses will not include the full resource representation,
-e.g.:
-
-```bash
-$ curl -X DELETE \  
-  https://service.com/apps/1f9b/dynos/05bd
-
-HTTP/1.1 202 Accepted
-Content-Type: application/json;charset=utf-8
-...
-{}
-```
-
-#### Accept serialized JSON in request bodies
-
-Accept serialized JSON on `PUT`/`PATCH`/`POST` request bodies, either
-instead of or in addition to form-encoded data. This creates symmetry
-with JSON-serialized response bodies, e.g.:
+#### 接受需求本體的序列化 JSON
 
+於 `PUT`、`PATCH`、`POST` 需求本體接受序列化 JSON，可與表單資料並存，或取代它。這與回應本體的序列化 JSON 取得平衡，例如：
 ```bash
 $ curl -X POST https://service.com/apps \
     -H "Content-Type: application/json" \
@@ -86,78 +16,3 @@ $ curl -X POST https://service.com/apps \
   ...
 }
 ```
-
-#### Use consistent path formats
-
-##### Resource names
-
-Use the plural version of a resource name unless the resource in question is a singleton within the system (for example, in most systems a given user would only ever have one account). This keeps it consistent in the way you refer to particular resources.
-
-##### Actions
-
-Prefer endpoint layouts that don’t need any special actions for
-individual resources. In cases where special actions are needed, place
-them under a standard `actions` prefix, to clearly delineate them:
-
-```
-/resources/:resource/actions/:action
-```
-
-e.g.
-
-```
-/runs/{run_id}/actions/stop
-```
-
-#### Downcase paths and attributes
-
-Use downcased and dash-separated path names, for alignment with
-hostnames, e.g:
-
-```
-service-api.com/users
-service-api.com/app-setups
-```
-
-Downcase attributes as well, but use underscore separators so that
-attribute names can be typed without quotes in JavaScript, e.g.:
-
-```
-service_class: "first"
-```
-
-#### Support non-id dereferencing for convenience
-
-In some cases it may be inconvenient for end-users to provide IDs to
-identify a resource. For example, a user may think in terms of a Heroku
-app name, but that app may be identified by a UUID. In these cases you
-may want to accept both an id or name, e.g.:
-
-```bash
-$ curl https://service.com/apps/{app_id_or_name}
-$ curl https://service.com/apps/97addcf0-c182
-$ curl https://service.com/apps/www-prod
-```
-
-Do not accept only names to the exclusion of IDs.
-
-#### Minimize path nesting
-
-In data models with nested parent/child resource relationships, paths
-may become deeply nested, e.g.:
-
-```
-/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}
-```
-
-Limit nesting depth by preferring to locate resources at the root
-path. Use nesting to indicate scoped collections. For example, for the
-case above where a dyno belongs to an app belongs to an org:
-
-```
-/orgs/{org_id}
-/orgs/{org_id}/apps
-/apps/{app_id}
-/apps/{app_id}/dynos
-/dynos/{dyno_id}
-```
diff --git a/requests/support-non-id-dereferencing-for-convenience.md b/requests/support-non-id-dereferencing-for-convenience.md
@@ -1,14 +1,11 @@
-#### Support non-id dereferencing for convenience
+#### 支援非 ID 的便利存取
 
-In some cases it may be inconvenient for end-users to provide IDs to
-identify a resource. For example, a user may think in terms of a Heroku
-app name, but that app may be identified by a UUID. In these cases you
-may want to accept both an id or name, e.g.:
+以 ID 來辨別資源對使用者來說有時很不方便。舉個例子，使用者會以 Heroku app 名稱來思考，但那個 app 可用 UUID 辨識。這種情況您會希望同時接受 ID 與名稱，例如：
 
 ```bash
 $ curl https://service.com/apps/{app_id_or_name}
 $ curl https://service.com/apps/97addcf0-c182
 $ curl https://service.com/apps/www-prod
 ```
 
-Do not accept only names to the exclusion of IDs.
+不要只接受名稱而排除 ID。