两周前因为公司一次裁人,好几个人的活都被按在了我头上,这其中的一大部分是一系列REST API,撰写者号称基本完成,我测试了一下,发现尽管从功能的角度来说,这些API实现了spec的显式要求,但是从实际使用的角度,欠缺的东西太多(各种各样的隐式需求)。REST API是一个系统的backend和frontend(或者3rd party)打交道的通道,承前启后,有很多很多隐式需求,比如调用接口与RFC保持一致,API的内在和外在的安全性等等,并非提供几个endpoint,返回相应的json数据那么简单。仔细研究了原作者的代码,发现缺失的东西实在太多,每个API基本都在各自为战,与其修补,不如重写(并非是程序员相轻的缘故),于是我花了一整周,重写了所有的API。稍稍总结了些经验,在这篇文章里讲讲如何撰写「合格的」REST API。 RFC一致性REST API一般用来将某种资源和允许的对资源的操作暴露给外界,使调用者能够以正确的方式操作资源。这里,在输入输出的处理上,要符合HTTP/1.1(不久的将来,要符合HTTP/2.0)的RFC,保证接口的一致性。这里主要讲输入的method/headers和输出的status code。 Methods HTTP协议提供了很多methods来操作数据: GET: 获取某个资源,GET操作应该是幂等(idempotence)的,且无副作用。 POST: 创建一个新的资源。 PUT: 替换某个已有的资源。PUT操作虽然有副作用,但其应该是幂等的。 PATCH(RFC5789): 修改某个已有的资源。 DELETE:删除某个资源。DELETE操作有副作用,但也是幂等的。 幂等在HTTP/1.1中定义如下: Methods can also have the property of “idempotence” in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. 如今鲜有人在撰写REST API时, 简单说来就是一个操作符合幂等性,那么相同的数据和参数下,执行一次或多次...
评论