A few of our friends have been asking us what are some of the best practices we learnt over the last two years designing and implementing RESTful Web Services as the back-end of the feedly service. Here is a quick/high level brain dump:
Phase 1 – Defining a simple resource/service | Take a sample resource such as Customer Information, model it as JSON. Build a simple servlet where PUT creates a new customer, GET returns the customer information based on the customer key, DELETE deletes the customer and POST updates the customer information. Make sure that PUT returns the right information regarding the URL of the newly created resource. In our case, we have a framework which maps JSON to our Java Model and use hibernate to persist that model in a MySQL database. The important things for this phase are to the JSON representation right and the base url formatting simple and clean. [Update: see some additional clarification regarding the use of PUT versus POST for creation and update at the end of this document]
Phase 2 – Implementing a client | Learn how to build a simple Javascript client which interacts with the service you built in phase one. This is AJAX 101. There are hundreds of libraries which help you abstract XMLHTTPRequest. Pick one that is cross browser. Pick one that is transparent enough to let you see the GET, POST, PUT and DELETE operations you are calling. JQuery is a great candidate. Some servers do not allow DELETE, in that case you need to learn how to do POST with an method overwrite.
Phase 3 – Adding validation | Change your service implementation to add some data validation to the JSON resource which is being received during PUT and POST. Learn how to use HTTP error code to define and transfer exception information. Learn how to handle those exceptions on the client side. The important thing for this phase is to make sure that you know the existing HTTP error codes, reuse them when it makes sense and create new one which are compliant with HTTP when needed.
Phase 4 – Complex resources | More services evolve over time into resources which are more complex/composite. This will have impact on your URL hierarchy. It will also have impact on the way you marshal those composite JSON resources into domain objects. Try extending the customer resource to include [1...N] address resources. Make sure that the new “service” allows you to get a customer with all its addresses but also allows you to get one address or add/edit/delete an address.
Phase 5 – Adding caching | The web infrastructure offers rich caching mechanisms (last modified information, cache duration, eTag). Learn about those mechanism and see if you can leverage them to improve the performance and scalability of your service. In the back end, learn about Memcached and see how you can leverage it to reduce the load on our service. This is all the more important when you start dealing with sets of large composite resources which are expensive database-wise to build but are not updated often (in those cases, it might be worth to building the resource once and asking the client to cache it if you know when it is going to expire or ask memcached to cache it you do not.
Phase 6 – Adding Authentication | Learn who to leverage your existing web authentication frameworks to for the user to login and validate credential before the service is accessed. Look at how you could use Open Id and OAuth if you are building a consumer centric service. Here again use existing HTTP error codes when possible.
Phase 7 – Publishing Business Events | Often, changes to resource require different types of back end processing. When possible try to avoid creating a monolithic service, instead, save the resource and fire a business event. Defining the right granularity for the business event and the right typing is hard. You might have to iterate a few time to get this right. My advice is to not over engineer it: keep it as simple as possible and re-factor as new use cases appear. For example, if you want to have some processing to send a new welcome email to each customer, define a ON_NEW_CUSTOMER event with a payload which includes the customer URI and instrument our service to fire that event each time a new customer is created.
Phase 7 – Adding Lifecycle | If your resource includes a life-cycle (example Order), your can model that life-cycle as part of the resource and use the state for the the validation in phase 3 and the published business events (state transitions are usually good candidates for business events).
We will try to add more as our back end evolves. We are also looking at taking some of our back-end infrastructure and open sourcing it. We should know more in the next few months. If you have any suggestions you would like to share please post them in the comments or send me an email to edwink@devhd.com and I will update this list. Thanks!
Update/May 27th, 2009: There has been some great comments regarding the use of PUT versus POST. So I did some additional research and found this interesting post.
The crux of the issue comes down to a concept known as idempotency. An operation is idempotent if a sequence of two or more of the same operation results in the same resource state as would a single instance of that operation. According to the HTTP 1.1 specification, GET, HEAD, PUT and DELETE are idempotent, while POST is not. That is, a sequence of multiple attempts to PUT data to a URL will result in the same resource state as a single attempt to PUT data to that URL, but the same cannot be said of a POST request.
After that discussion, a more realistic mapping would seem to be:
- Create = PUT iff you are sending the full content of the specified resource (URL).
- Create = POST if you are sending a command to the server to create a subordinate of the specified resource, using some server-side algorithm.
- Retrieve = GET.
- Update = PUT iff you are updating the full content of the specified resource.
- Update = POST if you are requesting the server to update one or more subordinates of the specified resource.
- Delete = DELETE.
Update July 8th 2009. Here is a great presentation from LinkedIn on how they use RESTful APIs for high performance integration. Great watch.
设计时注意以下非功能性需求:安全验证,数据校验,并发处理 和 可管理性(错误诊断等)
分享到:
相关推荐
无服务器架构的最佳实践全文共14页,当前为第1页。无服务器架构的最佳实践全文共14页,当前为第1页。 无服务器架构的最佳实践全文共14页,当前为第1页。 无服务器架构的最佳实践全文共14页,当前为第1页。 无服务器...
这些REST的关键原则与将你的 API 分割成逻辑资源紧密相关。使用HTTP请求控制这些资源,其中,这些方法(GET, POST, PUT, PATCH, DELETE)具有特殊含义。 一旦定义好了资源, 需要确定什么样的 actions 应用它们,...
本白皮书的目的是了解创建 RESTful API 涉及哪些约束以及 Web REST API 的最佳实践是什么。 REST 约束 客户端服务器 无国籍 缓存 统一界面 分层系统 按需代码(可选) 客户端服务器 客户端-服务器约束侧重于关注点...
REST是设计分布式网络服务或API时遵循的架构原则以及设计风格, 前后端分离最佳实践的开发标准或规范。本文为资料收藏的.md笔记,选取比较重要的资料,收集了以下内容: 重要概念介绍,如前述的第2-第4个关键词。 ...
RESTful图书管理系统架构设计-restful api 设计最佳实践WORD范本.docx
《iOS网络编程与云端应用最佳实践》是介绍iOS 6网络编程和云端应用开发技术书籍,介绍了苹果网络、数据交换格式、WebService、iCloud、定位服务、地图、推送通知、Newsstand、应用内购买、Passbook、以及社交网络...
Roy Felding 在他论文 network based software architectures 的 第五章 中首次介绍了这些原则。这些REST的关键
iOS网络编程与云端应用最佳实践》是介绍iOS 6网络编程和云端应用开发技术书籍,介绍了苹果网络、数据交换格式、Web Service、iCloud、定位服务、地图、推送通知、Newsstand、应用内购买、Passbook、以及社交网络编程...
Java EE 8设计模式和最佳实践 这是Packt发布的的代码存储库。 使用架构设计模式构建企业就绪的可扩展应用程序 这本书是关于什么的? 模式是Java开发人员必不可少的设计工具。 Java EE设计模式和最佳实践通过检查...
最佳实践 带有角度UI,REST服务和OSGi服务的OSGi应用程序。 该设计遵循OSGi R7应用程序的当前最佳实践。模组父级-定义常见的依赖关系和OSGi捆绑包的构建后端-Tasklist API,OSGi服务隐含和REST服务。 在功能完善的...
动手的RESTful API设计模式和最佳实践 这是Packt发布的“ 的代码存储库。 设计,开发和部署高度适应性,可扩展性和安全性的RESTful Web API 这本书是关于什么的? 本书介绍了代表性状态传输(REST)范例,该范例...
本书向读者介绍了什么是REST、什么是面向资源...本书详实、易懂,实战性强,提供了大量RESTful Web服务开发的最佳实践和指导,适合广大的Web开发人员、Web架构师及对Web开发或Web架构感兴趣的广大技术人员与学生阅读。
api样板具有最佳设计实践和学习知识的流明API的实现。 (DDD,CQRS,ES,Rest和GraphQL)去做一定有 升级到7.4稳定版 休息路线示例 DTO对象的设置系统 用于CQRS的Symfony消息总线 设置OpenApi解析方法 为资源设置...
方便的REST: RESTful逐渐成为了一种标准的服务器和客户端沟通的方式。你只需使用一行javascript代码,就可以快速的从服务器端得到数据。AugularJS将这些变成了JS对象,作为Model,遵循MVVM(modelview view-model)...
我从今年年初开始使用面向微服务的体系结构,我认为对于新手来说,简单地进行概念验证是很有用的,因为所有微服务的最佳实践都可以在实践中看到。 API设计与定义: 为了定义和设计微服务REST API,我们使用了Atom...
对于课程 ... 您将了解REST服务,什么是数据库以及如何使用它们,异步代码意味着什么,模板和路由是什么。...设计模式和最佳实践 Web包装 有用的链接 SoftUni SoftUni法官 Kinvey-进度软件 邮递员 车把 柴 摩卡
一个基于网络软件开发的研究项目,旨在实践广泛的技术、库、模式和最佳实践。 入门 (工作待定) 建筑学 该应用程序由多个模块组织在一起,以实现称为“端口和适配器”或简称为“六边形架构”的软件架构设计。 与...
thiwankakasun-REST-API设计用于咖啡店,使用JAVA和带有Spring的Mysql启动我创建了一个移动应用程序,以允许咖啡店客户在线订购咖啡。 我创建了简单的数据库结构来存储产品详细信息。我创建了简单的REST API来查看...
它最初是为 REST API 设计生成最佳实践的一种方式,我注意到 Zend 框架中缺少这种设计。 在此过程中,我使用了多个资源来帮助此扩展的设计部分。 回应 除非另有说明,否则发送的每个响应都应包含以下标头: 允许:...
OAuth构建于已被多个站点独立实现的已有协议和最佳化实践之上,是一个被大小服务提供者所支持、并为应用开发者和用户增进持续性和可信度的开放标准。 OAuth相关术语 服务提供方 Service Provider: 一个允许通过...