Web Api的设计与开发

端点的设计

端点:访问 API 的 URI

URI 和 HTTP方法 之间的关系,可以认为是操作对象和操作方法的关系。 URI = 操作对象 = 资源, HTTP方法 = 进行怎样的操作。
如果URI相同,但是HTTP方法不相同,对资源的处理也是不同的,可以是获取资源,更新资源,删除资源等。

端点设计时,需要遵循的原则:

  1. URI要短小,便于输入,不要有概念雷同的单词。
  2. URI的可读性要强,如果没有其他提示,人也能理解这个API的功能。最好不要过度使用单词的缩写形式。使用常用的英语单词。
  3. URI中大小写不要混用,最好都使用小写字母。HTTP协议中,指明了除了模式(schema)和主机名 之外,URI的其他部分都要区分大小写。
  4. URI要便于修改。能容易地从一个URI改为另一个 URI,如: /api/search/123/,可以猜测,修改这个 ID, 就可以获取其他信息。
  5. URI不要暴露服务器架构。不要暴露服务器端的开发语言,目录和系统结构等信息,可能会使服务器遭受攻击。
  6. URI要统一规范。单词的单复数,词性等,在一组API中要一致,参数的查询方式也要一致。