儒道哲學的浪漫人生

An intuitive API uses plural(複數的) rather than singular(單數的) nouns, and concrete(具體的) rather than abstract names.

• 在API URL中應該儘量使用複數名詞作為resource名稱，這樣有助於一致化URL的表達方式；另外名詞應該盡量具體，可以明白指出該resource代表什麼事物，例如用televisions代表電視，而盡量不要用electrics等較抽象的詞來代表電視。

Associations : “Resource almost always have relationships to other resources.” The relationships can be complex. Remember that once you have the primary key for one level, you usually don’t need to include the levels above because you’ve already got your specific object.

• Resource之間通常有關聯(Associations)，例如:某API可以get到ID為5678的owner所養的狗，他的URL可能長這樣: /owners/5678/dogs ，這代表dogs與owners的從屬關係。
• URL應盡量保持關係的簡化，不要讓URL表達的關係超過兩個Level。盡量讓URL表達的關係保持在Level N與Level N+1之間: /Resource level N/{ Resource N:Identifier}/ Resource level N+1.

Most APIs have intricacies(錯綜複雜的事物) beyond the base level of a resource. Make it simple for developers to use the base URL by putting optional states and attributes behind the HTTP question mark.

• Resource通常都有些屬性或狀態等複雜的描述，在使用URL時應該把這些複雜的描述放在question mark ‘?’之後，即用query string的方式表達resource的特別屬性或狀態。
• For Example:

GET /dogs?color=red&state=running&location=park

• API URL將會指定return所有正在公園裡亂跑的紅色的狗狗的資訊。

[參考] Web API Design - Crafting Interfaces tgat Develoers Love

      https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf

2018年6月8日星期五