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可以getID5678owner所養的狗,他的URL可能長這樣: /owners/5678/dogs ,這代表dogsowners的從屬關係。
  • URL應盡量保持關係的簡化,不要讓URL表達的關係超過兩個Level。盡量讓URL表達的關係保持在Level NLevel 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

 

201868日星期五

arrow
arrow

    jackterrylau 發表在 痞客邦 留言(0) 人氣()