葡京赌场网址RESTful API 设计指南 [转]

一、git clone

长距离操作的第一步,通常是起远程主机克隆一个本库,这时就要用git clone命令。

$ git clone <版本库的网址>

按照,克隆jQuery的版本库。

$ git clone https://github.com/jquery/jquery.git

拖欠命令会在该地主机生成一个目,与长途主机的版本库同名。如果假定指定不同之目录名,可以以目录名作为git clone指令的亚独参数。

$ git clone <版本库的网址> <本地目录名>

git clone支持多磋商,除了HTTP(s)以外,还支持SSH、Git、本地文件协议相当于,下面是局部事例。

$ git clone http[s]://example.com/path/to/repo.git/
$ git clone ssh://example.com/path/to/repo.git/
$ git clone git://example.com/path/to/repo.git/
$ git clone /opt/git/project.git 
$ git clone file:///opt/git/project.git
$ git clone ftp[s]://example.com/path/to/repo.git/
$ git clone rsync://example.com/path/to/repo.git/

SSH协议还有其余一样种植写法。

$ git clone [user@]example.com:path/to/repo.git/

平凡来说,Git协议下载速度最抢,SSH协议用于需要用户征的场合。各种协商优劣的详尽座谈要参考官文档。

 

阮一峰博客:http://www.ruanyifeng.com/blog/2014/06/git_remote.html

六、过滤信息(Filtering)

一经记录数据很多,服务器无可能都以它返回给用户。API应该提供参数,过滤返回结果。

下面是有的广的参数。

  • ?limit=10:指定返回记录之多少
  • ?offset=10:指定返回记录之开端位置。
  • ?page=2&per_page=100:指定第几页,以及每页的记录数。
  • ?sortby=name&order=asc:指定返回结果按谁属性排序,以及排序依次。
  • ?animal_type_id=1:指定筛选标准

参数的筹划允许在冗余,即许API路径和URL参数偶尔生双重。比如,GET
/zoo/ID/animals 和 GET /animals?zoo_id=ID 的义是一模一样的。

  • git clone
  • git remote
  • git fetch
  • git pull
  • git push

九、返回结果

对不同操作,服务器向用户返回的结果应当抱以下标准。

  • GET /collection:返回资源对象的列表(数组)
  • GET /collection/resource:返回单个资源对象
  • POST /collection:返回新生成的资源对象
  • PUT /collection/resource:返回完整的资源对象
  • PATCH /collection/resource:返回完整的资源对象
  • DELETE /collection/resource:返回一个空文档

Git有成百上千优势,其中有即是长距离操作十分省事。本文详细介绍5单Git命令,它们的概念以及用法,理解了这些情节,你便会见了控制Git远程操作。

四、路径(Endpoint)

途径而如”终点”(endpoint),表示API的切实可行网址。

以RESTful架构中,每个网址代表一致种资源(resource),所以网址中未能够发生动词,只能有名词,而且所用底名词往往与数据库的表格名对应。一般的话,数据库被的表都是同种记录之”集合”(collection),所以API中之名词也当下复数。

比方来说,有一个API提供动物园(zoo)的音信,还包各种动物及雇员的音讯,则它的门径应该设计成为下面这样。

  • https://api.example.com/v1/zoos
  • https://api.example.com/v1/animals
  • https://api.example.com/v1/employees

翻译博客(翻译的莫极端好):http://www.ihref.com/read-16369.html

二、域名

应该尽可能用API部署在专用域名之下。

https://api.example.com

只要确定API很简短,不会见产生愈来愈壮大,可以设想在主域名下。

https://example.org/api/

读github的好地方:

八、错误处理(Error handling)

假设状态码是4xx,就应往用户返回出错信息。一般的话,返回的消息中将error作为键名,出错信息作键值即可。

{
error: “Invalid API key”
}

从未有过烦视频:http://v.youku.com/v_show/id_XMTg0MjA2MzU3Ng==.html?spm=a2hzp.8244740.0.0&f=28783332

转自:http://www.ruanyifeng.com/blog/2014/05/restful\_api.html

 

本文针对初级用户,从最简易的云起,但是需要读者对Git的主导用法有了解。同时,本文覆盖了上面5单命的几拥有的常用用法,所以于熟练用户也产生参考价值。

一、协议

API与用户之通信协议,总是用HTTPs协议。

Git举凡时最盛的本管理体系,学会Git几乎成为了开发者的必备技能。

三、版本(Versioning)

有道是将API的版本号放入URL。

https://api.example.com/v1/

旁一样栽做法是,将版本号放在HTTP头信息中,但切莫若放入URL方便及直观。Github行使这种做法。

葡京赌场网址 1

七、状态码(Status Codes)

服务器向用户返回的状态码和提示信息,常见的来以下部分(方括号丁是该状态码对应之HTTP动词)。

  • 200 OK –
    [GET]:服务器成功返回用户请求的数目,该操作是幂等的(Idempotent)。
  • 201 CREATED – [POST/PUT/PATCH]:用户新建或改动数据成功。
  • 202 Accepted – [*]:表示一个请都跻身后台排队(异步任务)
  • 204 NO CONTENT – [DELETE]:用户删除数据成功。
  • 400 INVALID REQUEST –
    [POST/PUT/PATCH]:用户发生的伸手有错,服务器并未进展新建或改数据的操作,该操作是幂等的。
  • 401 Unauthorized –
    [*]:表示用户并未权力(令牌、用户称、密码错误)。
  • 403 Forbidden – [*]
    表示用户获得授权(与401不当相对),但是看是于禁止的。
  • 404 NOT FOUND –
    [*]:用户有的呼吁对的是休存在的记录,服务器并未进展操作,该操作是幂等的。
  • 406 Not Acceptable –
    [GET]:用户请求的格式不可得(比如用户要JSON格式,但是只有XML格式)。
  • 410 Gone -[GET]:用户请求的资源被永久删除,且非会见再度沾的。
  • 422 Unprocesable entity – [POST/PUT/PATCH]
    当创建一个目标时,发生一个证错误。
  • 500 INTERNAL SERVER ERROR –
    [*]:服务器出误,用户用无法判断出的伸手是否成功。

状态码的通通列表参见这里。

四、git pull

git pull命令的打算是,取回远程主机某个分支的创新,再跟地方的指定分支合并。它的一体化格式稍有些有硌复杂。

$ git pull <远程主机名> <远程分支名>:<本地分支名>

比如,取回origin主机的next旁,与当地的master子合并,需要写成下面这样。

$ git pull origin next:master

只要远程分支是与当前分合并,则冒号后面的一部分可概括。

$ git pull origin next

上面命令表示,取回origin/next分层,再同当前分合并。实质上,这同样于事先开git fetch,再做git merge

$ git fetch origin
$ git merge origin/next

于一些场合,Git会自动在地面分支和长途分支中,建立平等种植追踪关系(tracking)。比如,在git clone的上,所有地方分支默认与远程主机的同名分支,建立追踪关系,也就是说,本地的master旁自动”追踪”origin/master分支。

Git也同意手动建立追踪关系。

git branch --set-upstream master origin/next

点命令指定master分层追踪origin/next分支。

若果手上分和长途分支存在追踪关系,git pull即使好概括远程分支名。

$ git pull origin

上面命令表示,本地的手上支行自动和相应的origin长机”追踪分支”(remote-tracking
branch)进行统一。

假使手上子就来一个追踪分支,连远程主机名都可以简单。

$ git pull

上面命令表示,当前分自动和唯一一个追踪分支进行合并。

如统一需要以rebase模式,可以用--rebase选项。

$ git pull --rebase <远程主机名> <远程分支名>:<本地分支名>

设远程主机删除了某个分支,默认情况下,git pull 不会见在拉取远程分支的时节,删除相应之当地分支。这是为着防,由于其他人操作了长途主机,导致git pull不知不觉删除了本土分支。

可,你得变动之行为,加上参数 -p 就会见当地方去远程已经去的分。

$ git pull -p
# 等同于下面的命令
$ git fetch --prune origin 
$ git fetch -p

RESTful API 设计指南

 

纱应用程序,分为前端和后端两单部分。当前之发展趋势,就是前者设备层出不穷(手机、平板、桌面电脑、其他专用设备……)。

故而,必须来同一种统一之机制,方便不同的前端设备和后端进行通信。这致使API构架的盛行,甚至出现”API
First”的计划思想。RESTful
API举凡眼前可比成熟的平模仿互联网应用程序的API设计理论。我原先写过同样篇《理解RESTful架构》,探讨如何掌握这概念。

今日,我用介绍RESTful
API的设计细节,探讨如何设计同样拟合理、好用之API。我之要害参照了有限首稿子(1,2)。

葡京赌场网址 2

三、git fetch

要远程主机的版库有了更新(Git术语叫做commit),需要用这些创新取回本地,这时就要动用git fetch命令。

$ git fetch <远程主机名>

地方命令将某远程主机的翻新,全部取回本地。

git fetch命令通常用来查其他人的经过,因为她抱回的代码对君本地的开代码没有影响。

默认情况下,git fetch收复所有支行(branch)的更新。如果仅想取回特定分支的创新,可以指定分支名。

$ git fetch <远程主机名> <分支名>

比如,取回origin主机的master分支。

$ git fetch origin master

所取得回的翻新,在本地主机上一经为此”远程主机名/分支名”的形式读取。比如origin主机的master,就要用origin/master读取。

git branch命令的-r选取,可以据此来查看远程分支,-a选查看所有支行。

$ git branch -r
origin/master

$ git branch -a
* master
  remotes/origin/master

地方命令表示,本地主机的即分是master,远程分支是origin/master

取回远程主机的翻新后,可以于其的底蕴及,使用git checkout令创建一个新的分。

$ git checkout -b newBrach origin/master

上面命令表示,在origin/master的底子及,创建一个新分。

除此以外,也可行使git merge命令或者git rebase指令,在本土分支上合远程分支。

$ git merge origin/master
# 或者
$ git rebase origin/master

面命令表示于脚下子上,合并origin/master

十一、其他

(1)API的地位证明应使OAuth
2.0框架。

(2)服务器返回的多寡格式,应该尽可能采用JSON,避免以XML。

(完)

日期: 2014年6月12日

十、Hypermedia API

RESTful
API最好就Hypermedia,即返结果被提供链接,连于任何API方法,使得用户不查看文档,也掌握下一致步该做什么。

依,当用户为api.example.com的干净目录发出请求,会博得这样一个文档。

{“link”: {
“rel”: “collection https://www.example.com/zoos”,
“href”: “https://api.example.com/zoos”,
“title”: “List of zoos”,
“type”: “application/vnd.yourformat+json”
}}

上面代码表示,文档中出一个link属性,用户读取这个特性就亮下一样步该调用什么API了。rel代表这个API与目前网址的关联(collection关系,并给有该collection的网址),href代表API的路子,title表示API的题,type表示回去路。

Hypermedia
API的筹划为称为HATEOAS。Github的API就是这种计划,访问api.github.com会面沾一个备可用API的网址列表。

{
“current_user_url”: “https://api.github.com/user”,
“authorizations_url”: “https://api.github.com/authorizations”,
// …
}

自从地方可以观看,如果想博得当前用户的信息,应该去看api.github.com/user,然后便收获了下面结果。

{
“message”: “Requires authentication”,
“documentation_url”: “https://developer.github.com/v3”
}

点代码表示,服务器被起了提示信息,以及文档的网址。

作者: 阮一峰

五、HTTP动词

于资源的具体操作类型,由HTTP动词表示。

常用之HTTP动词有下面五独(括号里是对应之SQL命令)。

  • GET(SELECT):从服务器取出资源(一件或多起)。
  • POST(CREATE):在服务器新建一个资源。
  • PUT(UPDATE):在服务器更新资源(客户端提供反后底整资源)。
  • PATCH(UPDATE):在服务器更新资源(客户端提供反之性)。
  • DELETE(DELETE):从服务器删除资源。

还有个别单不常用之HTTP动词。

  • HEAD:获取资源的首任数据。
  • OPTIONS:获取信息,关于资源的哪些性是客户端好转移之。

下是部分事例。

  • GET /zoos:列出所有动物园
  • POST /zoos:新建一个动物园
  • GET /zoos/ID:获取有指定动物园的消息
  • PUT /zoos/ID:更新某个指定动物园的信(提供该动物园的全部音讯)
  • PATCH /zoos/ID:更新某个指定动物园的消息(提供该动物园的片信息)
  • DELETE /zoos/ID:删除某个动物园
  • GET /zoos/ID/animals:列出某个指定动物园的兼具动物
  • DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

二、git remote

为便于管理,Git要求每个远程主机都必须指定一个主机名。git remote令就用于管理主机名。

莫牵动选项的时,git remote命列出所有长途主机。

$ git remote
origin

使用-v慎选,可以参照远程主机的网址。

$ git remote -v
origin  git@github.com:jquery/jquery.git (fetch)
origin  git@github.com:jquery/jquery.git (push)

地方命令表示,当前单纯来同一玉远程主机,叫做origin,以及它的网址。

克隆版本库的时,所采取的长距离主机自动为Git命名为origin。如果想就此任何的主机名,需要用git clone命令的-o选择指定。

$ git clone -o jQuery https://github.com/jquery/jquery.git
$ git remote
jQuery

方命令表示,克隆的当儿,指定远程主机叫做jQuery。

git remote show指令加上主机名,可以查看该主机的详细信息。

$ git remote show <主机名>

git remote add令用于添加远程主机。

$ git remote add <主机名> <网址>

git remote rm命令用于去远程主机。

$ git remote rm <主机名>

git remote rename指令用于远程主机的化名。

$ git remote rename <原主机名> <新主机名>

博客:

五、git push

git push一声令下用于将本地分支的翻新,推送至长途主机。它的格式和git pull命相仿。

$ git push <远程主机名> <本地分支名>:<远程分支名>

留神,分支推送顺序的写法是<来源地>:<目的地>,所以git pull大凡<远程分支>:<本地分支>,而git push凡<本地分支>:<远程分支>。

假若看略远程分支名,则表示用地方分支推送和的有”追踪关系”的长距离分支(通常两者同名),如果该远程分支不在,则会为新建。

$ git push origin master

面命令表示,将当地的master支行推送到origin主机的master分段。如果后者不在,则会被新建。

要简单本地分支名,则意味去指定的远程分支,因为当时无异于于推送一个空的本地分支到长途分支。

$ git push origin :master
# 等同于
$ git push origin --delete master

上面命令表示去origin主机的master分支。

若果手上子和长途分支中是追踪关系,则地面分支和长途分支都得以概括。

$ git push origin

方命令表示,将眼前子推送到origin长机的附和分支。

假设手上子就生一个追踪分支,那么主机名都可以大概。

$ git push

若是手上子和多个主机是追踪关系,则可以应用-u慎选指定一个默认主机,这样后就可无加以其它参数使用git push

$ git push -u origin master

地方命令将地方的master旁推送至origin长机,同时指定origin呢默认主机,后面就是足以无加以另参数使用git push了。

切莫牵动其他参数的git push,默认只推送当前子,这名叫simple方式。此外,还有一样种植matching方式,会推送所生起照应的远程分支的地方分支。Git
2.0本子之前,默认使用matching方法,现在更改也默认使用simple方式。如果假定改者设置,可以利用git config命令。

$ git config --global push.default matching
# 或者
$ git config --global push.default simple

再有平等种情景,就是管是否存在对应的远距离分支,将地面的具备支行都推送到长途主机,这时要利用--all选项。

$ git push --all origin

上面命令表示,将兼具地方分支都推送到origin主机。

一经远程主机的本比地方本更新,推送时Git会报错,要求先行在当地做git pull合并差异,然后又推向送及长途主机。这时,如果你必要推送,可以使--force选项。

$ git push --force origin 

方命令下--force选,结果导致远程主机及创新的本被覆盖。除非您怪确定要这么做,否则该尽量避免使用--force选项。

最后,git push莫会见推送标签(tag),除非采用--tags选项。

$ git push origin --tags

(完)