译者前言: 首先这是一篇国外的英文文章,非常系统、详尽的介绍了如何使用PHP创建REST API,国内这方面的资料非常非常的有限,而且基本没有可操作性。这篇文章写的非常好,只要对PHP稍有了解的程序员,看完本文基本可以自己动手写 REST API,花了几个小时翻译过来和大家共享,希望可以帮助大家。转载请注明出处。 本文地址:http://hmw./blog/1190827 原文地址:Create a REST API with PHP One of the latest (sort of) crazes sweeping the net is APIs, more specifically those that leverage REST. It’s really no surprise either, as consuming REST APIs is so incredibly easy… in any language. It’s also incredibly easy to create them as you essentially use nothing more than an HTTP spec that has existed for ages. One of the few things that I give Rails credit for is its well thought-out REST support, both for providing and consuming these APIs (as its been explained by all the Rails fanboys I work with). 最近互联网上比较热门的一个名词是APIs(接口),特别是leverage REST。不过考虑到REST APIs在任何语言下都是非常的简单,也就没什么好惊奇的了。同时,它也是非常的容易创建,你基本只需要使用已经存在多年的HTTP规范就可以。我认为 Rails语言的为数不多的优点之一就是良好的REST支持,不仅是提供APIs,同时也有很多的客户端支持(我的一些Rails粉丝同事都向我解释了这 一点)。 Seriously, if you’ve never used REST, but you’ve ever had to work with (or worse, create) a SOAP API, or simply opened a WSDL and had your head explode, boy do I have good news for you! 认真的讲,假如你从来没有使用过REST,却曾经使用过SOAP API,或者只是简单的打开一个令人头大的WSDL文档。小伙子,我确实要带给你一个好消息! So, What on Earth is REST? Why Should You Care? 那么,究竟什么是REST?为什么你应该关心? Before we get into writing some code, I want to make sure everyone’s got a good understanding of what REST is and how its great for APIs. First, technically speaking, REST isn’t specific to just APIs, it’s more of a generic concept. However, obviously, for the sake of this article we’ll be talking about it in the context of an API. So, let’s look at the basic needs of an API and how REST addresses them. 在我们开始写代码之前,我想要确认每个人都可以很好的理解什么是REST以及它是如何 特别适合APIs的。首先,从技术上来讲,REST并不是仅仅特定于APIs应用,它更多的是一个通用的概念。然而,很明显,我们这篇文章所讨论的 REST就是在接口应用的环境下。因此,让我们看看一个API的基本要求已经REST如何处理他们。 Requests 请求 All APIs need to accept requests. Typically, with a RESTful API, you’ll have a well-defined URL scheme. Let’s say you want to provide an API for users on your site (I know, I always use the “users” concept for my examples). Well, your URL structure would probably be something like, “api/users” and “api/users/[id]” depending on the type of operation being requested against your API. You also need to consider how you want to accept data. These days a lot of people are using JSON or XML, and I personally prefer JSON because it works well with JavaScript, and PHP has easy functionality for encoding and decoding it. If you wanted your API to be really robust, you could accept both by sniffing out the content-type of the request (i.e. application/json or application/xml), but it’s perfectly acceptable to restrict things to one content type. Heck, you could even use simple key/value pairs if you wanted. 所有的APIs都需要接收请求。对于一个RESTful API,你需要一个定义好的URL规则,我们假定你想要提供一个接口给你网站上的用户(我知道,我总是使用"用户"这个概念来举例)。你的URL结构可能 类似于这样:"api/users"或者"api/users/[id]",这取决于请求接口的操作类型。同时,你也需要考虑你想要怎么样接收数据。近来 一段时间,很多人正在使用JSON或者XML,从我个人来讲,我更加喜欢JSON,因为它可以很好的和javascript进行交互操作,同时PHP也可 以很简单的通过json_encode和json_decode两个函数来对它进行编码和解码。如果你希望自己的接口真正强健,你应该通过识别请求的内容 类型(比如application/json或者application/xml)同时允许接收两种格式。但是,限制只接收一种类型的数据也是可以很好的 被接受。真见鬼,假如你愿意,你甚至可以使用简单的键/值对。 The other piece of a request is what it’s actually meant to do, such as load, save, etc. Normally, you’d have to come up with some sort of architecture that defines what action the requester (consumer) desires, but REST simplifies that. By using HTTP request methods, or verbs, we don’t need to define anything. We can just use the GET, POST, PUT, and DELETE methods, and that covers every request we’d need. You can equate the verbs to your standard crud-style stuff: GET = load/retrieve, POST = create, PUT = update, DELETE = well, delete. It’s important to note that these verbs don’t directly translate to CRUD, but it is a good way to think about them. So, going back to the above URL examples, let’s take a look at what some possible requests could mean: GET request to /api/users – List all users GET request to /api/users/1 – List info for user with ID of 1 POST request to /api/users – Create a new user PUT request to /api/users/1 – Update user with ID of 1 DELETE request to /api/users/1 – Delete user with ID of 1 一个请求的其他部分是它真正要做的事情,比如加载、保存等。通常来说,你应该提供几种 结构来定义请求者(消费者)所希望的操作,但是REST简化了这些。通过使用HTTP请求方法或者动作,我们不需要去额外定义任何东西。我们可以仅仅使用 GET,POST,PUT和DELETE方法,这些方法涵盖了我们所需要的每一个请求。你可以把它和标准的增删改查模式对应起来:GET=加载/检索 (查,select),POST=创建(增,Create),PUT=更新(改,update),DELETE=删除(DELETE)。我们要注意到,这 些动词并没有直接翻译成CRUD(增删改查),但是这个理解它们的一个很好的方法。因此,回到刚才所举的URL的例子,让我们看一下一些可能的请求的含 义: GET request to /api/users – 列举出所有的用户 GET request to /api/users/1 – 列出ID为1的用户信息 POST request to /api/users – 插入一个新的用户 PUT request to /api/users/1 – 更新ID为1的用户信息 DELETE request to /api/users/1 – 删除ID为1的用户 As you hopefully see, REST has already taken care of a lot of the major headaches of creating your own API through some simple, well-understood standards and protocols, but there’s one other piece to a good API… 正如你所希望看到的,REST已经解决了很多令人头疼的创建接口的问题,通过一些简单的,容易理解的标准和协议。但是一个好的接口还要另外一个方面... Responses 响应 So, REST handles requests very easily, but it also makes generating responses easy. Similar to requests, there are two main components of a RESTful response: the response body, and a status code. The response body is pretty easy to deal with. Like requests, most responses in REST are usually either JSON or XML (perhaps just plain text in the case of POSTs, but we’ll cover that later). And, like requests, the consumer can specify the response type they’d like through another part of the HTTP request spec, “Accept”. If a consumer wishes to receive an XML response, they’d just send an Accept header as a part of their request saying as much (”Accept: application/xml”). Admittedly, this method isn’t as widely adopted (tho it should be), so you have can also use the concept of an extension in the URL. For example, /api/users.xml means the consumer wants XML as a response, similarly /api/users.json means JSON (same for things like /api/users/1.json/xml). Either way you choose (I say do both), you should pick a default response type as a lot of the time people wont’ even tell you what they want. Again, I’d say go with JSON. So, no Accept header or extension (i.e. /api/users) should not fail, it should just fail-over to the default response-type. 所以,REST可以很简单的处理请求,同时它也可以简单的处理响应。和请求类似,一个 RESTful的响应主要包括两个主要部分:响应体和状态码。响应体非常容易去处理。就像请求,大部分的REST响应通常是JSON或者XML格式(也许 对POST操作来说仅仅是纯文本,我们稍后会讨论),和请求类似,消费者可以通过设置HTTP规范的"Accept"选项来规定自己做希望接收到的响应数 据类型。如果一个消费者希望接收到XML响应,他们仅仅需要发送一个包含类似于(”Accept: application/xml”)这样的头信息请求。不可否认,这种方式并没有被广泛的采用(即使应该这样),因此你也可以使用URL后缀的形式,例 如:/api/users.xml意味着消费者希望得到XML响应,同样,/api/users.json意味着JSON格式的响应(/api /users/1.json/xml也是一样)。不管你采用哪一种方法,你都需要设定一个默认的响应类型,因为很多时候人们并不会告诉你他们希望什么格 式。再次地,我会选择JSON来讨论。所以,没有Accept头信息或者扩展(例如:/api/users)不应该失败,而是采用默认的响应类型。 But what about errors and other important status messages associated with requests? Easy, use HTTP status codes! This is far and above one of my favorite things about creating RESTful APIs. By using HTTP status codes, you don’t need to come up with a error / success scheme for your API, it’s already done for you. For example, if a consumer POSTS to /api/users and you want to report back a successful creation, simply send a 201 status code (201 = Created). If it failed, send a 500 if it failed on your end (500 = Internal Server Error), or perhaps a 400 if they screwed up (400 = Bad request). Maybe they’re trying to POST against an API endpoint that doesn’t accept posts… send a 501 (Not implemented). Perhaps your MySQL server is down, so your API is temporarily borked… send a 503 (Service unavailable). Hopefully, you get the idea. If you’d like to read up a bit on status codes, check them out on wikipedia: List of HTTP Status Codes. 但是和请求有关的错误和其他重要的状态信息怎么办呢?简单,使用HTTP的状态码!这 是我创建RESTful接口最喜欢的事情之一。通过使用HTTP状态码,你不需要为你的接口想出error/success规则,它已经为你做好。比如: 假如一个消费者提交数据(POST)到/api/users,你需要返回一个成功创建的消息,此时你可以简单的发送一个201状态码 (201=Created)。如果失败了,服务器端失败就发送一个500(500=内部服务器错误),如果请求中断就发送一个400(400=错误请 求)。也许他们会尝试向一个不接受POST请求的接口提交数据,你就可以发送一个501错误(未执行)。又或者你的MySQL服务器挂了,接口也会临时性 的中断,发送一个503错误(服务不可用)。幸运的是,你已经知道了这些,假如你想要了解更多关于状态码的资料,可以在维基百科上查找:List of HTTP Status Codes。 I’m hoping you see all the advantages you get by leveraging the concepts of REST for your APIs. It really is super-cool, and its a shame its not more widely talked about in the PHP community (at least as far as I can tell). I think this is likely due to the lack of good documentation on how to deal with requests that aren’t GET or POST, namely PUT and DELETE. Admittedly, it is a bit goofy dealing with these, but it certainly isn’t hard. I’m also sure some of the popular frameworks out there probably have some sort of REST implementation, but I’m not a huge framework fan (for a lot of reasons that I won’t get into), and it’s also good to know these things even if somebody’s already created the solution for you. 我希望你能看到REST接口的这些优点。它真的超级酷。在PHP社区社区里没有被广泛 的讨论真是非常的遗憾(至少我知道的是这样)。我觉得这主要是由于没有很好的文档介绍如何处理除了GET和POST之后的请求,即PUT和DELETE。 不可否认,处理这些是有点傻,但是却不难。我相信一些流行的框架也许已经有了某种REST的实现方式,但是我不是一个框架粉丝(原因有很多),并且即使有 人已经为你提供了解决方案,你知道这些也是非常有好处的。 If you’re still not convinced that this is a useful API paradigm, take a look at what REST has done for Ruby on Rails. One of its major claims to fame is how easy it is to create APIs (through some sort of RoR voodoo, I’m sure), and rightly so. Granted I know very little about RoR, but the fanboys around the office have preached this point to me many times. But, I digress… let’s write some code! 如果你还是不太自信这是一个非常有用的API范式,看一下REST已经为Ruby on Rails做了什么。其中最令人称道的就是创建接口的便利性(通过某种RoR voodoo,我确信),而且确实如此。虽然我对RoR了解很少,但是办公室的Ruby粉丝们向我说教过很多次。不好意思跑题了,让我们开始写代码。 Getting Started with REST and PHP 开始使用PHP写REST One last disclaimer: the code we’re about to go over is in no way intended to be used as an example of a robust solution. My main goal here is to show how to deal with the individual components of REST in PHP, and leave creating the final solution up to you. 最后一项免责声明:我们接下来提供的代码并不能被用来作为一个稳健的解决方案。我的主要目的是向大家展示如果使用PHP处理REST的每个单独部分,而把最后的解决方案留给你们自己去创建。 So, let’s dig in! I think the best way to do something practical is to create a class that will provide all the utility functions we need to create a REST API. We’ll also create a small class for storing our data. You could also then take this, extend it, and apply it to your own needs. So, let’s stub some stuff out: 那么,让我们开始深入代码。我认为做一个实际事情做好的方法就是新建一个class, 这个class将提供创建REST API所需要的所有功能性方法。现在我们新建一个小的class来存储我们的数据。你可以把它拿去扩展一下然后应用到自己的需求中。我们现在开始写点东 西: class RestUtils { public static function processRequest(){ } public static function sendResponse($status = 200, $body = '', $content_type = 'text/html'){ } public static function getStatusCodeMessage($status){ // these could be stored in a .ini file and loaded // via parse_ini_file()... however, this will suffice // for an example // 这些应该被存储在一个.ini的文件中,然后通过parse_ini_file()函数来解析出来,然而这样也足够了,比如: $codes = Array( 100 => 'Continue', 101 => 'Switching Protocols', 200 => 'OK', 201 => 'Created', 202 => 'Accepted', 203 => 'Non-Authoritative Information', 204 => 'No Content', 205 => 'Reset Content', 206 => 'Partial Content', 300 => 'Multiple Choices', 301 => 'Moved Permanently', 302 => 'Found', 303 => 'See Other', 304 => 'Not Modified', 305 => 'Use Proxy', 306 => '(Unused)', 307 => 'Temporary Redirect', 400 => 'Bad Request', 401 => 'Unauthorized', 402 => 'Payment Required', 403 => 'Forbidden', 404 => 'Not Found', 405 => 'Method Not Allowed', 406 => 'Not Acceptable', 407 => 'Proxy Authentication Required', 408 => 'Request Timeout', 409 => 'Conflict', 410 => 'Gone', 411 => 'Length Required', 412 => 'Precondition Failed', 413 => 'Request Entity Too Large', 414 => 'Request-URI Too Long', 415 => 'Unsupported Media Type', 416 => 'Requested Range Not Satisfiable', 417 => 'Expectation Failed', 500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway', 503 => 'Service Unavailable', 504 => 'Gateway Timeout', 505 => 'HTTP Version Not Supported' ); return (isset($codes[$status])) ? $codes[$status] : ''; } } class RestRequest { private $request_vars; private $data; private $http_accept; private $method; public function __construct(){ $this->request_vars = array(); $this->data = ''; $this->http_accept = (strpos($_SERVER['HTTP_ACCEPT'], 'json')) ? 'json' : 'xml'; $this->method = 'get'; } public function setData($data){ $this->data = $data; } public function setMethod($method){ $this->method = $method; } public function setRequestVars($request_vars){ $this->request_vars = $request_vars; } public function getData(){ return $this->data; } public function getMethod(){ return $this->method; } public function getHttpAccept(){ return $this->http_accept; } public function getRequestVars(){ return $this->request_vars; } }
OK, so what we’ve got is a simple class for storing some information about our request (RestRequest), and a class with some static functions we can use to deal with requests and responses. As you can see, we really only have two functions to write… which is
the beauty of this whole thing! Right, let’s move on… public static function processRequest(){
// get our verb 获取动作
$request_method = strtolower($_SERVER['REQUEST_METHOD']);
$return_obj = new RestRequest();
// we'll store our data here 在这里存储请求数据
$data = array();
switch ($request_method){
// gets are easy...
case 'get':
$data = $_GET;
break;
// so are posts
case 'post':
$data = $_POST;
break;
// here's the tricky bit...
case 'put':
// basically, we read a string from PHP's special input location,
// and then parse it out into an array via parse_str... per the PHP docs:
// Parses str as if it were the query string passed via a URL and sets
// variables in the current scope.
parse_str(file_get_contents('php://input'), $put_vars);
$data = $put_vars;
break;
}
// store the method
$return_obj->setMethod($request_method);
// set the raw data, so we can access it if needed (there may be
// other pieces to your requests)
$return_obj->setRequestVars($data);
if(isset($data['data'])){
// translate the JSON to an Object for use however you want
$return_obj->setData(json_decode($data['data']));
}
return $return_obj;
}
Like I said, pretty straight-forward. However, a few things to note… First, you typically don’t accept data for DELETE requests, so we don’t have a case for them in the switch. Second, you’ll notice that we store both the request variables, and the parsed JSON data.
This is useful as you may have other stuff as a part of your request (say an API key or something) that isn’t truly the data itself (like a new user’s name, email, etc.). $data = RestUtils::processRequest(); switch($data->getMethod){ case 'get': // retrieve a list of users break; case 'post': $user = new User(); $user->setFirstName($data->getData()->first_name); // just for example, this should be done cleaner // and so on... $user->save(); break; // etc, etc, etc... }
Please don’t do this in a real app, this is just a quick-and-dirty example. You’d want to wrap this up in a nice control structure with everything abstracted properly, but this should help you get an idea of how to use this stuff. But I digress, let’s move
on to sending a response. public static function sendResponse($status = 200, $body = '', $content_type = 'text/html'){ $status_header = 'HTTP/1.1 ' . $status . ' ' . RestUtils::getStatusCodeMessage($status); // set the status header($status_header); // set the content type header('Content-type: ' . $content_type); // pages with body are easy if($body != ''){ // send the body echo $body; exit; } // we need to create the body if none is passed else { // create some body messages $message = ''; // this is purely optional, but makes the pages a little nicer to read // for your users. Since you won't likely send a lot of different status codes, // this also shouldn't be too ponderous to maintain switch($status) { case 401: $message = 'You must be authorized to view this page.'; break; case 404: $message = 'The requested URL ' . $_SERVER['REQUEST_URI'] . ' was not found.'; break; case 500: $message = 'The server encountered an error processing your request.'; break; case 501: $message = 'The requested method is not implemented.'; break; } // servers don't always have a signature turned on (this is an apache directive "ServerSignature On") $signature = ($_SERVER['SERVER_SIGNATURE'] == '') ? $_SERVER['SERVER_SOFTWARE'] . ' Server at ' . $_SERVER['SERVER_NAME'] . ' Port ' . $_SERVER['SERVER_PORT'] : $_SERVER['SERVER_SIGNATURE']; // this should be templatized in a real-world solution $body = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <title>' . $status . ' ' . RestUtils::getStatusCodeMessage($status) . '</title> </head> <body> <h1>' . RestUtils::getStatusCodeMessage($status) . '</h1> ' . $message . ' <hr /> <address>' . $signature . '</address> </body> </html>'; echo $body; exit; } }
That’s It! We technically have everything we need now to process requests and send responses. Let’s talk a bit more about why we need to have a standard body response or a custom one. For GET requests, this is pretty obvious, we need to send XML / JSON content
instead of a status page (provided the request was valid). However, there’s also POSTs to deal with. Inside of your apps, when you create a new entity, you probably fetch the new entity’s ID via something like mysql_insert_id(). Well, if a user posts to your
API, they’ll probably want that new ID as well. What I’ll usually do in this case is simply send the new ID as the body (with a 201 status code), but you could also wrap that in XML or JSON if you’d like. switch($data->getMethod){ // this is a request for all users, not one in particular case 'get': $user_list = getUserList(); // assume this returns an array if($data->getHttpAccept == 'json'){ RestUtils::sendResponse(200, json_encode($user_list), 'application/json'); }else if ($data->getHttpAccept == 'xml') { // using the XML_SERIALIZER Pear Package $options = array ( 'indent' => ' ', 'addDecl' => false, 'rootName' => $fc->getAction(), XML_SERIALIZER_OPTION_RETURN_RESULT => true ); $serializer = new XML_Serializer($options); RestUtils::sendResponse(200, $serializer->serialize($user_list), 'application/xml'); } break; // new user create case 'post': $user = new User(); $user->setFirstName($data->getData()->first_name); // just for example, this should be done cleaner // and so on... $user->save(); // just send the new ID as the body RestUtils::sendResponse(201, $user->getId()); break; }
Again, this is just an example, but it does show off (I think, at least) how little effort it takes to implement RESTfulstuff. // figure out if we need to challenge the user if(empty($_SERVER['PHP_AUTH_DIGEST'])) { header('HTTP/1.1 401 Unauthorized'); header('WWW-Authenticate: Digest realm="' . AUTH_REALM . '",qop="auth",nonce="' . uniqid() . '",opaque="' . md5(AUTH_REALM) . '"'); // show the error if they hit cancel die(RestControllerLib::error(401, true)); } // now, analayze the PHP_AUTH_DIGEST var if(!($data = http_digest_parse($_SERVER['PHP_AUTH_DIGEST'])) || $auth_username != $data['username']) { // show the error due to bad auth die(RestUtils::sendResponse(401)); } // so far, everything's good, let's now check the response a bit more... $A1 = md5($data['username'] . ':' . AUTH_REALM . ':' . $auth_pass); $A2 = md5($_SERVER['REQUEST_METHOD'] . ':' . $data['uri']); $valid_response = md5($A1 . ':' . $data['nonce'] . ':' . $data['nc'] . ':' . $data['cnonce'] . ':' . $data['qop'] . ':' . $A2); // last check.. if($data['response'] != $valid_response) { die(RestUtils::sendResponse(401)); }
|
|