Digest | API最佳实践, 17个改变世界的方程

>  2021年04月19日信息消化

### 22个最佳实践，让你的API设计技能更上一层楼

原文：[22 Best Practices to Take Your API Design Skills to the Next Level](https://betterprogramming.pub/22-best-practices-to-take-your-api-design-skills-to-the-next-level-65569b200b9)

1. Use kebab-case for URLs `/system-orders`

2. Use camelCase for Parameters: `/system-orders/{orderId}`

3. Plural Name to Point to a Collection `GET /users`

4. URL Starts With a Collection and Ends With an Identifier `GET /shops/:shopId/ or GET /category/:categoryId`

5. Keep Verbs Out of Your Resource URL

6. Use camelCase for JSON property

7. Monitoring

1. RESTful HTTP services MUST implement the /health and /version and /metrics API endpoints. They will provide the following info.

8. Don’t Use table_name for the Resource Name

9. Use API Design Tools

1. [API Blueprint](https://apiblueprint.org/)
   2. [Swagger](https://swagger.io/)

10. Use Simple Ordinal Number as Version
    http://api.domain.com/v1/shops/3/products

11. Include Total Number of Resources in Your Response

12. Accept limit and offset Parameters

`GET /shops?offset=5&limit=5`

13. Take fields Query Parameter `GET /shops?fields=id,name,address,contact`

14. Don’t Pass Authentication Tokens in URL

15. Validate the Content-Type

16. Use HTTP Methods for CRUD Functions

17. Use the Relation in the URL For Nested Resources

18. CORS

1. Do support CORS (Cross-Origin Resource Sharing) headers for all public-facing APIs.

19. Security

1. Enforce HTTPS (TLS-encrypted) across all endpoints, resources, and services.

20. Errors

1. Do return `4xx` HTTP error codes when rejecting a client request due to one or more Service Errors.

21. **Golden Rules**

1. Flat is better than nested.
    2. Simple is better than complex.
    3. Strings are better than numbers.
    4. Consistency is better than customization.

### 其他值得阅读

#### 设计个人logo的5个步骤

[5 steps to designing a personal logo (that you don't hate)](https://dribbble.com/stories/2021/04/20/design-your-personal-logo)

##### 第一步：定义你的品牌

作为设计师，我们可能会花很多时间专注于定义别人的品牌，有时会忽略自己的品牌。但在你开始为自己设计标志之前，你应该花些时间思考是什么让你的品牌独一无二。

想出几个描述你品牌的关键词，并以此作为设计你的标志的起点。

> Step 1: Define your brand
> As designers, we can spend so much time focusing on defining other people’s brands that we sometimes neglect our own. But before you embark on designing a logo for yourself, you should spend some time thinking about what makes your brand unique.
>
> Come up with a few keywords that describe your brand and use that as a starting point for designing your logo.

##### 第2步：研究你的竞争对手

在你对创建标志背后的目的和你的品牌是什么有了一个很好的想法之后，现在是时候开始收集一些灵感，并检查你的竞争对手在做什么。

从那里，查看你所仰慕的设计师的标志，以及其他创意公司的标志。开始用logo和其他你喜欢的设计元素，包括排版和调色板来创建情绪板。

> Step 2: Research your competition
> After you have a good idea of the purpose behind creating a logo and what your brand is all about, it’s time to start collecting some inspiration and checking out what your competition is doing.
>
> From there, check out logos from designers you look up to, as well as logos from other creative companies. Start creating moodboards with logos and other design elements you like, including typography and color palettes.

##### 第3步：决定你的标志的正确格式类型

你可以为你的个人品牌选择几种基本类型的标志。请注意，有些类型的标志甚至可以结合起来。

> Step 3: Decide on the right type of format for your logo
>
> There are a few basic types of logos that you can choose from for your personal brand. Note that some types of logos can even be combined:

抽象标志是创意专业人员的最佳选择。它们可以紧密代表现实世界的物品，也可以完全是概念性的。在如何使用抽象风格的标志方面，设计师有很大的自由度。

> Abstract logos are an excellent choice for creative pros. They can closely represent real-world items, or be entirely conceptual. There’s a lot of freedom available to designers in how they use an abstract-style logo.

![Logos of 2020 by Alexandra Necula](https://raw.githubusercontent.com/Phalacrocorax/memo-image-host/master/uPic/c781d40fa319c6919ed478128bb30e3c.jpg)

##### 第四步：测试概念

虽然我通常不建议为客户设计一堆不同的模型（太多的选择会导致选择瘫痪或导致弗兰肯斯坦式的设计），但当你设计你自己的标志时，规则是不同的。我仍然不建议创建几十个不同的标志模型，但如果你没有立即知道你想去的方向，创建3-5个是有意义的。

> Step 4: Test the concept
> While I often don’t recommend designing a bunch of different mockups for clients (too many options can cause choice paralysis or result in a Frankenstein-esque design), when you’re designing your own logo the rules are different. I still don’t recommend creating dozens of different logo mockups, but creating 3-5 makes sense if you don’t immediately know the direction you want to go in.

##### 第五步：完善你的最爱

一旦你创建了一些你喜欢的、适合你的品牌的模拟图，现在是时候挑选一个继续前进并完善它了。清理排版，调整标志配色方案，并对整体设计进行任何微小的调整。这个阶段的目标是使你的标志看起来尽可能的专业。

> Step 5: Refine your favorite
> Once you’ve created some mockups you like and that fit your brand, it’s time to pick one to move forward with and refine it. Clean up the typography, adjust the logo color scheme and make any minor adjustments to the overall design. The goal in this stage of the process is to make your logo look as professional as possible.

### 一点收获

- Twitter上刷到的[17 Equations That Changed the World](https://twitter.com/CliffSiong/status/1382926618297921541/photo/1)