如何创建没有动词的REST URL?

我正在努力确定如何设计宁静的网址。 我为所有使用带有名词的URL的宁静方式而不是动词不明白如何做到这一点。

我们正在创建一项实施金融计算器的服务。 该计算器带有一堆我们将通过CSV文件上传的参数。 用例包括:

  • 上传新参数
  • 获取最新参数
  • 获取给定商业日期的参数
  • 使一组参数处于活动状态
  • 验证一组参数
  • 我收集宁静的方法将是有以下类型的网址:

    /parameters
    /parameters/12-23-2009
    

    您可以通过以下方式实现前三种用例:

  • POST在发布请求中包含参数文件的位置
  • 第一个URL的GET
  • 获取第二个网址
  • 但是,如何在没有动词的情况下做第4个和第5个用例呢? 你不需要像下面这样的URL吗?

    /parameters/ID/activate
    /parameters/ID/validate
    

    ??


    也许是这样的:

    PUT /parameters/activation HTTP/1.1
    Content-Type: application/json; encoding=UTF-8
    Content-Length: 18
    
    { "active": true }
    

    良好URI设计的一般原则:

  • 不要使用查询参数来改变状态
  • 如果你能帮助它, 不要使用混合路径。 小写是最好的
  • 不要在URI中使用特定于实现的扩展(.php,.py,.pl等)
  • 不要使用您的URI进入RPC
  • 不要限制你的URI的空间尽可能地
  • 保持路径段短
  • 难道不是选/resource/resource/ ; 从您不使用的那个创建301重定向
  • 使用查询参数进行资源的子选择; 即分页,搜索查询
  • 动东西了URI的,应该是在HTTP报头或身体
  • (注意:我没有说“RESTful URI设计”; URI在REST中本质上是不透明的。)

    HTTP方法选择的一般原则:

  • 永远不要使用GET来改变状态; 这是让Googlebot毁了你一天的好方法
  • 除非您正在更新整个资源,否则不要使用PUT
  • 除非您也可以合法地在同一个URI上进行GET,否则不要使用PUT
  • 不要使用POST来检索长寿命或可能合理缓存的信息
  • 不要执行与PUT无幂相关的操作
  • 使用GET为尽可能
  • 不要使用POST优先有疑问时放
  • 不要使用POST时,你必须做一些事情,感觉RPC样
  • 不要使用PUT对资源类,较大或分层
  • 不要使用优先删除张贴到移除资源
  • 使用GET的东西像计算,除非你的投入很大,在这种情况下使用POST
  • 使用HTTP进行Web服务设计的一般原则:

  • 不要将元数据放在应该在标题中的响应正文中
  • 不要将元数据放在单独的资源中,除非包含它会造成很大的开销
  • 使用适当的状态码
  • 201 Created资源后创建; 资源必须在发送响应时存在
  • 202 Accepted成功执行操作或异步创建资源后202 Accepted
  • 当有人对显然是虚假的数据进行操作时, 400 Bad Request ; 对于您的应用程序,这可能是验证错误; 通常为未捕获的异常保留500
  • 401 Unauthorized当有人访问您的API时没有提供必要的Authorization标头或Authorization内的凭证无效时未经Authorization ; 如果您不希望通过Authorization标头获得凭据,请不要使用此响应代码。
  • 403 Forbidden当某人以恶意或未经授权访问您的API时被禁止
  • 405 Method Not Allowed有人在使用POST时应该使用PUT等
  • 413 Request Entity Too Large当有人试图向您发送无法接受的大文件时, 413 Request Entity Too Large
  • 尝试用茶壶冲泡咖啡时, 418 I'm a teapot一个茶壶
  • 不要使用缓存头时,您可以
  • 当您可以轻松地将资源减少到散列值时, ETag头部是很好的
  • Last-Modified应该告诉你,保持资源更新的时间戳是个好主意
  • Cache-ControlExpires应该被赋予合理的值
  • 你所能兑现在请求缓存头( If-None-ModifiedIf-Modified-Since
  • 难道当他们使用感重定向,但这些应该是罕见的Web服务
  • 关于你的具体问题,POST应该用于#4和#5。 这些操作属于上述“类RPC”指导原则。 对于#5,记住POST不一定要使用Content-Type: application/x-www-form-urlencoded 。 这可能很容易成为JSON或CSV有效负载。


    每当它看起来你需要一个新的动词时,想想把这个动词变成一个名词来代替。 例如,将'激活'转为'激活','验证'为'验证'。

    但是从你写的内容来看,我会说你的应用程序有更大的问题。

    每当提出一个名为“参数”的资源时,它应该在每个项目团队成员的头脑中发出红旗。 '参数'可以从字面上适用于任何资源; 它不够具体。

    “参数”究竟代表什么? 可能有很多不同的东西,每个东西都应该有一个独立的资源专用于它。

    解决这个问题的另一种方式是 - 当你与最终用户讨论你的应用程序时(那些对编程知之甚少的人)他们自己反复使用的单词是什么?

    这些是你应该围绕你的应用程序设计的词汇。

    如果您尚未与潜在用户进行此转换,请立即停止所有操作,直到您完成后再写下其他代码! 只有到那时,你的团队才会明白需要建立什么。

    我对金融软件一无所知,但如果我不得不猜测,我会说一些资源可能会通过诸如“报告”,“付款”,“转账”和“货币”等名称。

    这部分软件设计过程中有许多好书。 两个我可以推荐的是域驱动设计和分析模式。

    链接地址: http://www.djcxy.com/p/6999.html

    上一篇: How to create REST URLs without verbs?

    下一篇: RESTful URL design for search