PHP Web Services Basic Documentation Release 1.0-draft Kamal Mustafa March 14, 2016 Contents 1 Introduction 3 1.1 SOAP vs XMLRPC vs HTTP/REST...................................3 1.2 HTTP/REST...............................................4 1.3 Security - Use SSL............................................4 2 Data Format / Serialization 5 2.1 Encoding/Decoding...........................................5 2.2 Defining Status Code...........................................6 3 Authentication 9 3.1 Example.................................................9 4 Testing and Debugging 11 5 Full Example 13 6 Indices and tables 15 i ii PHP Web Services Basic Documentation, Release 1.0-draft Contents: Contents 1 PHP Web Services Basic Documentation, Release 1.0-draft 2 Contents CHAPTER 1 Introduction Web services are client and server applications that communicate over the World Wide Web’s (WWW) HyperText Transfer Protocol (HTTP). As described by the World Wide Web Consortium (W3C), web services provide a stan- dard means of interoperating between software applications running on a variety of platforms and frameworks. Web services are characterized by their great interoperability and extensibility, as well as their machine-processable de- scriptions, thanks to the use of XML. Web services can be combined in a loosely coupled way to achieve complex operations. Programs providing simple services can interact with each other to deliver sophisticated added-value services. 1.1 SOAP vs XMLRPC vs HTTP/REST SOAP and XMLRPC are ways to expose certain operations of the application over the network. For example, if the application has a function called getUser($username), the function can be accessed using XML such as: <?xml version="1.0"?> <soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope" soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"> <soap:Body xmlns:m="http://www.example.org/"> <m:getUser> <m:username>kamal</m:username> </m:getUser> </soap:Body> </soap:Envelope> On the server side, to expose the above function, we also need to write another XML in a format called WSDL (Web Services Description Language). The file will be more verbose and details than above and most of the time, not written by hand but instead being generated with a special program that scan our application source code. REST on the other hand is a way to expose data (called Resource) over the web using HTTP. For example, we may have a resource called User, exposed through HTTP as: http://www.example.org/User Having above resource, we can use standard HTTP method to do operations such as: GET http://www.example.org/User/kamal POST http://www.example.org/User DELETE http://www.example.org/User/kamal 3 PHP Web Services Basic Documentation, Release 1.0-draft Again, this is the major difference between SOAP and REST:- • SOAP exposed a set of operations. • REST exposed a set of resources (data). 1.2 HTTP/REST The key principles of REST involve separating your API into logical resources. These resources are manipulated using HTTP requests where the method (GET, POST, PUT, PATCH, DELETE) has specific meaning. But what can be a resource ? Well, these should be nouns (not verbs!) that make sense from the perspective of the API consumer. Although your internal models may map neatly to resources, it isn’t necessarily a one-to-one mapping. The key here is to not leak irrelevant implementation details out to your API! Once you have your resources defined, you need to identify what actions apply to them and how those would map to your API. RESTful principles provide strategies to handle CRUD actions using HTTP methods mapped as follows: • GET /tickets - Retrieves a list of tickets • GET /tickets/12 - Retrieves a specific ticket • POST /tickets - Creates a new ticket • PUT /tickets/12 - Updates ticket #12 • PATCH /tickets/12 - Partially updates ticket #12 • DELETE /tickets/12 - Deletes ticket #12 The great thing about REST is that you’re leveraging existing HTTP methods to implement significant functionality on just a single /tickets endpoint. 1.3 Security - Use SSL Always use SSL. No exceptions. Today, your web APIs can get accessed from anywhere there is internet (like libraries, coffee shops, airports among others). Not all of these are secure. Many don’t encrypt communications at all, allowing for easy eavesdropping or impersonation if authentication credentials are hijacked. Another advantage of always using SSL is that guaranteed encrypted communications simplifies authentication efforts - you can get away with simple access tokens instead of having to sign each API request. 4 Chapter 1. Introduction CHAPTER 2 Data Format / Serialization 2.1 Encoding/Decoding To enable seemless integration between our web services and the applications that consume it, we need to have standard data format. The most common one is to use JSON. In PHP, there are 2 main function used to read and write JSON format: <?php $user = array( 'id' => 1, 'username' => 'Kamal', 'profiles' => array( 'credits' => 100, 'address' => 'JB', ), ); echo json_encode($user); Above code will produce JSON string that look like: {"id":1,"username":"Kamal","profiles":{"credits":100,"address":"JB"}} Conversely, when reading data submitted using our web service endpoint, we can use json_decode function. Let say user submit to us the above JSON string, can read it as: <?php $data = file_get_contents('php://input'); $data_json = json_decode($data, true); print_r($data_json); When user send the request, they will get back the same data: curl -v -d'{"id":1,"username":"Kamal","profiles":{"credits":100,"address":"JB"}}' -H 'Content-Type: application/json' http://localhost:4000/user.php * About to connect() to localhost port 4000 (#0) * Trying ::1... Connection refused * Trying 127.0.0.1... connected * Connected to localhost (127.0.0.1) port 4000 (#0) > POST /user.php HTTP/1.1 > User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8z zlib/1.2.5 > Host: localhost:4000 > Accept: */* 5 PHP Web Services Basic Documentation, Release 1.0-draft > Content-Type: application/json > Content-Length: 69 > < HTTP/1.1 200 OK < Host: localhost:4000 < Connection: close < X-Powered-By: PHP/5.4.43 < Content-type: text/html < Array ( [id] => 1 [username] => Kamal [profiles] => Array ( [credits] => 100 [address] => JB ) ) * Closing connection #0 2.2 Defining Status Code It’s very important when building web services, all requests get a standardized status or error code. HTTP already pro- vides rich status code to indicate various state of the request. Our REST API can use this status codes to communicate with our users. Below are among the most common use status code:- 2.2.1 200 OK This response code indicates that the request was successful. 2.2.2 201 Created This indicates the request was successful and a resource was created. It is used to confirm success of a PUT or POST request. 2.2.3 400 Bad Request The request was malformed. This happens especially with POST and PUT requests, when the data does not pass validation, or is in the wrong format. 2.2.4 404 Not Found This response indicates that the required resource could not be found. This is generally returned to all requests which point to a URL with no corresponding resource. 6 Chapter 2. Data Format / Serialization PHP Web Services Basic Documentation, Release 1.0-draft 2.2.5 401 Unauthorized This error indicates that you need to perform authentication before accessing the resource. 2.2.6 405 Method Not Allowed The HTTP method used is not supported for this resource. 2.2.7 409 Conflict This indicates a conflict. For instance, you are using a PUT request to create the same resource twice. 2.2.8 500 Internal Server Error When all else fails; generally, a 500 response is used when processing fails due to unanticipated circumstances on the server side, which causes the server to error out. 2.2. Defining Status Code 7 PHP Web Services Basic Documentation, Release 1.0-draft 8 Chapter 2. Data Format / Serialization CHAPTER 3 Authentication A RESTful API should be stateless. This means that request authentication should not depend on cookies or sessions. Instead, each request should come with some sort authentication credentials. By always using SSL, the authentication credentials can be simplified to a randomly generated access token that is delivered in the user name field of HTTP Basic Auth. The great thing about this is that it’s completely browser explorable - the browser will just popup a prompt asking for credentials if it receives a 401 Unauthorized status code from the server. 3.1 Example Below is an example of using HTTP Basic authentication in PHP: <?php $api_credentials = array( 'user1' => 'abc123', 'user2' => 'abcxyz' ); if (!isset($_SERVER['PHP_AUTH_USER'])) { header('WWW-Authenticate: Basic realm="My API"'); header('HTTP/1.1 401 Unauthorized'); exit; } else { $username = $_SERVER['PHP_AUTH_USER']; $password = $_SERVER['PHP_AUTH_PW']; if (!array_key_exists($username, $api_credentials)) { header('HTTP/1.1 403 Forbidden'); exit; } if ($password != $api_credentials[$username]) { header('HTTP/1.1 403 Forbidden'); exit; } } The $api_credentials above simply store the user’s credentials details such as username and password in a PHP array, hardcoded in the source code but in practice you’ll store the information in database such as MySQL. 9 PHP Web Services Basic Documentation, Release 1.0-draft 10 Chapter 3. Authentication CHAPTER 4 Testing and Debugging One advantage of using HTTP based API is there are lot of existing tools that can be used to test and debug