10 CHAPTER 1. THE BASICS
1.1.2.1 GitHub: An Ideal Example
The current GitHub v3 API [2] is a beautiful example of a properly-abstracted HTTP API. Each
of the popular HTTP verbs are used where applicable. Endpoints don’t have verbs in the name.
Interacting with an endpoint feels much like one is working with a representation of an object,
instead of performing actions.
An example of a good endpoint is GET /repos/{user id}/{repo id}/notifications. This
is obviously the endpoint used for getting a list of notifications of a particular repository. The
{user id}/{repo id} convention for referring to a repository is one understood by most users of
GitHub (repository names aren’t globally unique, only unique to a particular user). The only thing
that could be improved may be to not shorten repositories to repos and organizations to orgs
in the names of endpoints, although repo is well understood.
1.1.2.2 Twitter: A Flawed Example
The current Twitter v1.1 API [3] has some abstraction shortcomings with their data and business-
logic, as far as being an HTTP API is concerned. The API only makes use of the GET and POST
methods for interacting with data. Due to this shortcoming, most endpoint names are a pair of
noun and verbs.
One such example is POST /statuses/destroy/{status id}, used for deleting a status. A
cleaner version of this endpoint would be DELETE /statuses/{status id}. Also worth noting is
the differentiation of POST /statuses/update with media and POST /statuses/update. Both of
these endpoints are used for creating a new tweet, however the prior allows for the attachment of
media. These two endpoints should be combined into a single POST /statuses, with the media
related attributes being optional.
These endpoints are also an example of a bad nomenclature. Users of Twitter don’t think of
using the service as updating their status, they think of it as tweeting. This is something that may
have changed throughout the lifetime of the service, and if so would be a good candidate to change
between API versions. The Collection used by the aforementioned Endpoints would therefor be
better named tweets.
1.2 Anatomy of an HTTP Message
Since HTTP is the protocol we’re using to build our API, let’s examine some raw HTTP messages.
It’s surprising how many developers who have been building websites for years don’t know what
an HTTP message looks like! When the Consumer sends a request to the Server, it provides a
Request-Line and a set of Key/Value pairs called headers. For POST, PUT, and PATCH requests
it also provides two newlines and then the the request body. All This information is sent in the
same HTTP request (although this request can be broken up into multiple network packets if the
message is large enough).
The Server then replies in a similar format, first with a Status-Line and headers, and typically
two newlines followed by a body (the body is technically optional, as you’ll find out later). HTTP
is very much a request/response protocol; there is no push support (the Server does not send data
to the Consumer unprovoked). To do that you would need to use a different protocol such as
Websockets.
剩余57页未读，继续阅读
Joe叔
- 粉丝: 13
- 资源: 2
我的内容管理
展开
最新资源
- AirKiss技术详解：无线传递信息与智能家居连接
- Hibernate主键生成策略详解
- 操作系统实验：位示图法管理磁盘空闲空间
- JSON详解：数据交换的主流格式
- Win7安装Ubuntu双系统详细指南
- FPGA内部结构与工作原理探索
- 信用评分模型解析：WOE、IV与ROC
- 使用LVS+Keepalived构建高可用负载均衡集群
- 微信小程序驱动餐饮与服装业创新转型：便捷管理与低成本优势
- 机器学习入门指南：从基础到进阶
- 解决Win7 IIS配置错误500.22与0x80070032
- SQL-DFS：优化HDFS小文件存储的解决方案
- Hadoop、Hbase、Spark环境部署与主机配置详解
- Kisso：加密会话Cookie实现的单点登录SSO
- OpenCV读取与拼接多幅图像教程
- QT实战：轻松生成与解析JSON数据
资源上传下载、课程学习等过程中有任何疑问或建议，欢迎提出宝贵意见哦~我们会及时处理！
点击此处反馈
