标签: api-design

我有一个JSON REST API.有一个握手会给你一个有效15分钟的令牌.你在15分钟内完成的所有电话都可以正常工作.15分钟后,我返回一个错误对象(包括代码,消息,成功=假)但我也想知道我应该返回什么HTTP错误代码？并将使用HTTP错误代码搞乱某些客户端？(HTML5,iPhone,Android).在这种情况下,什么是最佳做法？

似乎今天有两类API用于网站.

1. 允许网站功能扩展的API,如Facebook,Myspace等.这些API似乎非常多样化.

2. API允许与Twitter,Flickr等现有网站功能进行交互.这些API都声称是基于REST的,但实际上只是"HTTP上的数据".

如果您正在创建允许功能扩展和外部交互的网站,那么您将使用哪些现有API作为参考模型？

背景:

我正在我的大学上课,名为"软件约束".在第一次讲座中,我们学习了如何构建优秀的API.

我们得到一个非常糟糕的API函数的一个很好的例子是public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);C#中的套接字.该函数接收3个套接字列表,并销毁它们,使得用户必须克隆所有套接字才能将它们送入Select().它还有一个超时(以微秒为单位),它是一个int,用于设置服务器等待套接字的最长时间.这个限制是+/- 35分钟(因为它是一个int).

问题:

1. 你如何将API定义为"坏"？
2. 你如何将API定义为"好"？

需要考虑的要点:

• 难以记住的函数名称.
• 功能参数很难理解.
• 文档不好.
• 一切都是如此相互关联,如果你需要更改1行代码,你实际上需要在其他地方更改数百行.
• 破坏其论点的函数.
• 由于"隐藏"的复杂性导致可扩展性差.
• 用户/ dev需要围绕API构建包装器以便可以使用它.

正如大多数人现在痛苦地意识到的那样,用于处理日历日期的Java API(特别是类java.util.Date和java.util.Calendar)是一个糟糕的混乱.

脱离我的头顶:

• 日期是可变的
• 日期表示时间戳,而不是日期
• 没有简单的方法来转换日期组件(日,月,年...)和日期
• 日历使用起来很笨,并试图将不同的日历系统组合成一个类

这篇文章总结得很好,JSR-310也解决了这些问题.

现在我的问题是:

这些类是如何进入Java SDK的？大多数这些问题看起来相当明显(特别是Date是可变的)并且应该很容易避免.那怎么回事？时间压力？或者回想起来的问题是否明显？

我意识到这不是一个严格的编程问题,但我发现理解API设计如何出错是很有趣的.毕竟,错误总是一个很好的学习机会(我很好奇).

在维基百科条目约得墨忒耳定律指出:

法律可以简单地称为"仅使用一个点".

但是,一个简单的流畅界面示例可能如下所示:

static void Main(string[] args)
{
   new ZRLabs.Yael.Pipeline("cat.jpg")
        .Rotate(90)
        .Watermark("Monkey")
        .RoundCorners(100, Color.Bisque)
        .Save("test.png");
}

那么这一起呢？

API端点是'方法',如https://api.foursquare.com/v2/venues/或包含非查询字符串参数的完整URL,如 https://api.foursquare.com/v2/venues/ 5104

换句话说,这两个独立的端点是否被认为是相同的端点？ http://myapi.com/somemodel/1
http://myapi.com/somemodel/2

我需要为文件上传服务创建一个REST API,允许用户:

1. 打开一个会话
2. 上传一堆文件
3. 关闭会话

然后,回过头来处理他们在上一个会话中上传的文件.

为了便于处理有关每个文件的数据并处理文件本身的内容,这是我正在考虑使用的URI方案:

/sessions/
/sessions/3
/sessions/3/files
/sessions/3/files/5
/sessions/3/file/5/content
/sessions/3/file/5/metadata

这将允许文件元数据与文件内容分开处理.在这种情况下,文件内容和文件元数据只允许GET ,并且要更新任何一个,新文件必须是PUT.

这有意义吗？如果没有,为什么以及如何更好？

在设计资源层次结构时,何时应该使用子资源？

我曾经认为,当一个资源不能存在而没有另一个资源时,它应该被表示为它的子资源.我最近跑过这个反例:

• 所有公司的员工都是唯一可识别的.
• 员工的访问控制和生命周期取决于公司.

我把它建模为: /companies/{companyName}/employee/{employeeId}

请注意,我不需要查找公司以找到员工,我也应该这样做？如果我这样做,我付出代价来查找我不需要的信息.如果我不这样做,这个URL错误地返回HTTP 200:

/companies/{nonExistingName}/employee/{existingId}

1. 我应该如何表示属于另一个资源的事实？
2. 我应该如何表示没有另一个资源无法识别资源的事实？
3. 子资源意味着什么关系,而不是模型？

我看了一下API版本的最佳实践？,但我不太相信答案,所以我再次用更具体的例子质疑版本控制部分.我有两个URI(一个版本作为URI的一部分,一个没有):

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123             

我怀疑第一个链接是否表达了REST的想法.我觉得很http://xxxx/v1/user/123困惑,因为它表明有一天会有更高的api版本http://xxxx/v2/user/123.但这在REST术语中没有意义,api版本本身是HTTP 1.0或1.1,它已经在HTTP请求中发送.这个以REST资源为中心的视图与其他api接口(如SOAP或Java接口)非常不同(其中通常有限定名称的api版本).

在REST中,版本控制唯一有意义的是该资源的表示(例如,添加或删除新字段).此版本控制属于内容协商的部分,如:

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

人们还可以争辩说,这样的版本内容协商可能是路径中URI的一部分,但我觉得它反直觉,因为你最终可能会为同一资源使用不同的URI,并且必须在某些时候维护重定向.

总结:在REST URI中,没有api版本,只有资源表示的版本控制.表示版本信息属于内容协商(作为queryParam或HTTP'接受').

你怎么看？你不同意/同意哪些事情？

我正在查看Java 8 中的Duration类,并注意到它没有:

long toSeconds();

但它有其他所有toXXXXX()可以获得天,小时,分钟,毫秒,纳米.我确实看到一个getSeconds()方法返回此持续时间对象中的秒数.还有一种get(TemporalUnit unit)方法可以将持续时间作为请求的时间单位.但为什么不保持toSeconds()方法的一致性？