jiepang API 初级教程

这篇文章是街旁档案的作者Scott撰写的街旁Open API教程，如果你刚刚接触街旁的API，那么你可以通过下面的教程对街旁API的开发有一个初步的了解。这篇教程将手把手教你创建一个简单的街旁应用。

如果你还不清楚开放平台/OpenAPI/JSON/OAuth是什么，或是如何配置服务器（没关系，我在写街旁档案之前通通不会），请先阅读文末的附录：预备知识。

欢迎指出任何错误/问题。

1. 一个例子

以下通过一个简单的例子，让你对街旁OpenAPI有一个直观的认识。（我就是这么走过来的呀（感叹状））

以locations/show这个API为例。这个API的作用是获取地点信息，如地主，惊喜，经纬度等等。

在浏览器地址栏中输入以下地址：

http://api.jiepang.com/v1/locations/show?guid=909E9F8AC5F24E5D&source=100000

其中，http://api.jiepang.com/v1/locations/show为API地址；参数guid为街旁地点id，值为909E9F8AC5F24E5D，是园咖啡在街旁的地点ID；参数source为街旁应用的App ID。

便会得到街旁服务器返回的一串JSON数据，像这个样子：
{
"tel": "010-62558788",
"checkin_num": 104,
"guid":"909E9F8AC5F24E5D",
"mayor": {
"nick":"SottiX",
"avatar_thumb":"http://img.jiepang.com/avatar/08/263566308_thumb.jpg",
"avatar_small":"http://img.jiepang.com/avatar/08/263566308_small.jpg",
"id": 263566308,
"avatar":"http://img.jiepang.com/avatar/08/263566308.jpg"
},
"addr": "海淀区西苑草场5号畅春园食街A10号(近北京大学西门)",
"name": "园·咖啡",
……………………
}
以上JSON数据表示了园咖啡的地点数据，如电话是010-62558788，地主是我（哇咔咔），地址在畅春园食街A10等等。

在你的应用中，调用API的过程十分类似，只是需要用某种服务器端/客户端脚本调用而已。

2. Here we go

2.1 创建应用

在街旁开发者的管理应用界面创建你的应用。网站地址和logo如果还没有确定，可以先随便填一个，之后可以随时改。

创建完毕之后，便会得到一个App ID和App Secret（如下图），这两个值是你的应用独有的，在调用API的时候需要一并传入。

准备完毕，开始coding吧！

2.2 The coding part

这里以PHP为例，其他语言类似。

首先请在这里下载接下来要用到的代码示例。这个代码示例是在官方PHP示例的基础上修改得到的（原版在这里），感谢原版作者lqs同学。

包中有以下5个文件：

jiepang.api.php为用OAuth调用API的封装类。其中需要用到的方法会在接下来的实例中介绍。

jiepang.api.config.php为配置文件。在实际使用中，你需要用2.1创建应用中获得的App ID和App Secret，以及你应用中的回调页面替换掉现有值。

demo下为一个程序实例。

demo/index.php为获取OAuth授权链接的页面：

view plainode>require_once '../jiepang.api.php';
$jiepang = new JiepangApi();

$auth_url = $jiepang->get_authorize_url();
首先创建一个JiepangApi实例。然后调用该实例的get_authorize_url方法。若不清楚OAuth验证流程，请参考文末附录『预备知识』中相关部分。get_authorize_url这个方法的返回值为街旁给出的OAuth授权页面，你需要将用户引导到这个页面进行授权。
demo/callback.php为OAuth授权回调页，会取得access
view plain token并存入session中，以便之后使用：

require_once '../jiepang.api.php';
$jiepang = new JiepangApi();
session_start();

$token = $jiepang->request_access_token();
$_SESSION['access_token'] = $token['access_token'];
// store the access token for later use
先创建一个JiepangApi实例，调用这个实例的request_access_token方法。该方法会返回access token。简单来说，access token就是街旁给你的用户授权的凭证，之后你每次调用需要验证的API都需要传入这个参数。Access token并不需要你每次都手动传入，这已经被封装到JiepangAPI类中，但这也意味着你（必要时）需要调用JiepangApi实例的set_access_token方法，将这个token写入实例。view plain

以上是用户登录时后台需要做的事。接下来demo/list_friends.php会尝试调用几个API：

require_once '../jiepang.api.php';
session_start();
$jiepang = new JiepangApi();
$user_info = $jiepang->api('account/verify_credentials');

if (array_key_exists('error', $user_info) && array_key_exists('code', $user_info['error']) && $user_info['error']['code'] == 52)
{
// invalid access token, needs re-authorization
// TODO redirect to authorization page
die();
}
$friends = array();
$page = 1;
do
{
$res = $jiepang->api('/friends/list', array('page' => $page));
$friends = array_merge($friends, $res['items']);
$page++;
}
while ($res['has_more']);
仍然是首先创建JiepangAPI实例。在JiepangAPI的构造方法中，会检查session中有没有access token，如果有的话直接写入实例。但是，如果之前没有把access token存入session，则需要调用JiepangAPI的set_access_token方法设置。

值得一提的是，这个access token是会过期的，这也意味着（technically）你每次调用任何API时，都需要检查返回值是不是52号错误：无效的Access Token。如果是，那么说明你使用的access token已经过时，你需要重新进行一遍用户授权：将用户引导到授权页，回调获取access token，这样才能继续调用API。但是在实际应用中，由于access token的有效期很长，为方便起见，只需要在用户每次登陆应用时检查accesstoken有效性即可。比如在本例中，我们在调用account/verify_credentials后检查了access token的有效性。

有了access token之后，调用API的步骤就很简单了：调用JiepangApi实例的api方法，第一个参数为API的名字，第二个参数为传入的参数（默认为空）。我们首先调用了account/verify_credentials（无参数），得到了用户的基本信息，如用户名、昵称、头像、ID等等。然后，我们反复调用了friends/list，并传入page=$page（返回第$page页的结果），得到了用户的全部好友。关于该API的参数说明，请参考这里。

api方法的返回值是关联数组，比如本例中$use
view plainr_info的内容像这样：

Array (
[city] => 北京
[name] => xxx
[sex] => male
[nick] => xxx
[birthday] => 0000-xx-xx
[avatar] => http://img.jiepang.com/avatar/xx/xxxxxx.jpg
[id] => xxx
[type] => 0
[email] => xxx@xxx.com
)
于是我们可以用形如$user_info['nick']的方式访问其中的数据。在接下来的html中，我们把得到的数据列了出来。
以上演示了用用街旁API的基本步很简单的实例，但是借助街旁API文档，你可以容易地根据你的需要扩展它。

2.3 一些经验之谈

我还想说几点我在使用API时得到的经验。

在用户登录时就调用account/verify_credentials。这是唯一一个可以直接告诉你登录用户id的API，而你总是要用到登陆用户id的。users/show并不能取代它，因为users/show需要传入用户id。

考虑将access token存储在客户端（比如用cookie），这样就不用用户每次访问应用都要重新验证了。

用户登录时检验access token有效性（之前已经提到过），若无效则需要重定向到授权页面，让用户重新授权。

嗯我要说的就是这些，希望对你有所帮助。在此期待你哦大作！

附录. 预备知识

1. 开放平台是什么

以下定义摘自Wikipedia：

In software and web-based architectures, an Open platform describes a software system which is based on open standards, such as published and fully documented external programming interfaces that allow using the software to function in other ways than the original programmer intended, without requiring modification of the source code.

Using an openplatform a developer could add features or functionality that the platform vendor hadn’t completed or hadn’t conceived of.

开放平台让软件/网站与第三方开发者合作，达到双赢的结果。一个软件/网站可以通过提供开放平台，让第三方开发者为自己干活，增加新的功能，扩大知名度和影响力；而开发者也可以利用开放平台提供者的数据、影响力、普及度等优势，强化自己的应用。

2. Open API是什么

一个开放平台的Open API跟一个软件/网站的内部API没什么两样，都是interface。不知道API是什么？那就把它理解为库函数好了。你在你的程序中调用它，它给你返回结果。

3. OAuth是什么

OAuth是一种验证方式，你或许已经见过并且用过。OAuth允许你在网站A上用开放平台B的帐号登录时，不需要输入你在B的用户名和密码，而是被引导到一个B的页面，在此点击一个类似“同意授权”的按钮，网站A就可以访问你在网站B帐号的信息。这样的好处是，网站A无法记录你的帐号密码。

有几个概念需要首先说明：

• Callback（回调）。回调页面是用户授权结束后，重定向到的页面。你需要在向街旁请求授权页面地址时告知这个回调页面的地址。
• Access token。你的网站访问街旁的数据需要一个凭证来代替BasicAuth中的用户名和密码，这个凭证叫做access token，用户给你授权之后街旁会给你这个token。之后你找街旁要数据的时候，都要拿着这个token。Access token是会过期的，当它过期时，你需要让用户重新授权，以获得新的access token。

要使用本例提供的JiepangAPI类，你还需要简单了解OAuth验证的流程：

1. 从街旁获取授权页面地址。
2. 将用户引导至该授权页面。
3. 用户授权之后，授权页面会重定向到回调页，并传给你一个code参数。
4. 在回调页中，你需要用这个code换取一个access token。需要指出的是，由于获取accesstoken需要这个code参数，而每个code只能用一次，因此用户每次授权，你只能请求得到一个access token。
5. 拿到了access token，你就可以去调用你需要的API了。

了解以上这些，对应用街旁API就足够了。如果有兴趣的话可以继续阅读OAuth基础教程和OAuth协议文档。

4. JSON是什么

街旁的Open API返回值采用JSON格式。

JSON是一种数据格式，与XML类似。JSON用序列化文本表示树结构的数据，每个节点是一个值(value)或映射(key->value)，如以下JSON串表示了一个菜单的内容和动作：

{
"menu": {
"id":"file",
"value":"File",
"popup":{
"menuitem":[
{"value":"New", "onclick": "CreateNewDoc()"},
{"value":"Open", "onclick": "OpenDoc()"},
{"value":"Close", "onclick": "CloseDoc()"}
]
}
}}
如果有兴趣，可以在这里深入了解JSON，以及JSON与XML的比较。

5. 关于配置服务器

街旁目前不提供站内应用服务，所以你的应用只能依托于一个独立网站，或是桌面/移动客户端。如果你的应用是一个网站，那么你会需要先在本地配置服务器。我用的是Apache+ PHP。关于配置的步骤，网上有许多很详细的教程，比如这个，这里就不细说了。