TheCloneArmy/RestApiGuide
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fixed info box title

Browse Source
This commit is contained in:
Todd Fredrich
2023-01-20 19:18:34 -07:00
parent 2a36363604
commit 99760ce0f3
1 changed files with 3 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
content/basics/restquicktips.md
View File

@ -27,7 +27,7 @@ GET requests MUST not change any underlying resource data. Measurements and trac
{{% /notice %}}
## Provide Sensible Resource Names
{{% notice tip "Verb-Free URLs" %}}
{{% notice tip "Art and Science" %}}
Producing a great API is 80% art and 20% science. Creating a URL hierarchy representing sensible resources is the art part. Having sensible resource names (which are just URL paths, such as /customers/12345/orders) improves the clarity of what a given request does. As humans are involved in understanding an API, this clarity counts.
{{% /notice %}}
@ -66,9 +66,9 @@ Suggested usages for the "Top 10" HTTP Response Status Codes are as follows:
| 500 INTERNAL SERVER ERROR | __Never return this intentionally.__ The general catch-all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end. |
## Support JSON
Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, schema validation and namespaces. If you must provide both JSON and XML let consumers switch between formats using the HTTP Accept header: application/json or application/xml.
Favor JSON support unless you're in a highly-standardized and regulated industry that requires XML, schema validation and namespaces. If you must provide both JSON and XML let consumers switch between formats using the HTTP `Accept` header: `application/json` or `application/xml`.
Be aware that as soon as we start talking about XML support, we start talking about schemas for validation, namespaces, etc. Unless required by your industry, avoid supporting all that complexity initially, if ever. JSON is designed to be simple, terse and functional.
Be aware that as soon as we start talking about XML support, we start talking about schemas for validation, namespaces, etc. Unless required by your industry, avoid supporting all that complexity initially, if ever. JSON is designed to be simple, fairly terse and functional.
## Create Fine-Grained Resources
When starting out, it's best to create APIs that mimic the underlying application domain or database architecture of your system. Eventually, you'll want aggregate services that utilize multiple underlying resources to reduce chattiness. However, it's much easier to create larger resources later from individual resources than it is to create fine-grained or individual resources from larger aggregates. Make it easy on yourself and start with small, easily defined resources, providing CRUD functionality on those. You can create those use-case-oriented, chattiness-reducing resources later.