Building RESTful Web Services with PHP 7: Lumen, Composer, API testing, Microservices, and more

Now, we know what a web service is. So proceeding to REST, it is important to know the need for a web service. Where can a web service be used?

As just defined, a web service is a system to machine-to-machine inter-operable communication over a network. It is very useful for communication between different systems or devices. In our case, we will be using web services to provide an interface by which either a mobile application or a web application will be able to communicate with a server to get and store data. This will make the client-side application separate from the server side logic. And nowadays, SPAs (Single Page Applications) and mobile applications need to be stand alone, separate from server side and only interacting with server side logic with web services. So definitely web services are very much important nowadays. However, web service usage is not limited to client side application usage but it is also useful in server to server communication where one server acts as a client.

REST is about separating the client and server. This constraint is about "separation of concerns". It means that the server and client have separate responsibilities, so one is not responsible for the other's duties. For example, the client is not responsible for data storage on the server as it is the server's responsibility. In the same way, the server doesn't need to know the user interface. So both the server and perform their tasks and fulfill their own responsibilities which makes their work easier. Hence, the server can be more scalable and the user interface on the client can be independent and more interactive.

Client server communication is stateless. Each request coming from the client will have all the information required to serve a request. This means there is no state in communication other than what is in the request. The response which the client will get will be based on the request without looking at any state other than what is in request.

If the session needs to be maintained, the session will be stored based on a token or identifier which is coming in the request. So if we look at an example of a web request, then the flow of HTTP is no more than a request sent by the client to the server and a response, sent back to the client from the server, as shown in the following diagram:

If a session needs to be maintained, the session data will be stored on the server, while the session identifier will be sent back to the client. In subsequent requests, the client will include that session identifier in every request by which the server will identify the client and load the related session's data as explained in the following diagram:

And in subsequent requests:

So REST is stateless. To maintain the state, one needs to pass an identifier or any other information, to logically group different requests to maintain a session in the request. If no such identifier is passed in the request, the server will never know if those two requests are from same client.

The advantage of statelessness is simplicity. The same requests will not result in different responses unless the request parameters are changed. It will return different based on different request parameters not due to some sort of state. Even the state depends on requests, as shown in the preceding example. So that session identifier is in the request, which can result in a different state and, hence, results in a different response.

This constraint specifies that a RESTful web response must define itself as cache-able or not, so that the client can know whether it should be cached or not. If it is correctly defined, it can result in less overhead and better performance because the client will not go to the server if it is able to use the cached version.

The uniform interface is the most distinguishing constraint. It basically the architecture makes the interface separate from the implementation, just as any system does.

It is similar to how it is in OOP: an interface separates the implementation and declaration. It is similar to how an operating system separates the user interface from the complex implementation logic that keeps our software's running.

The uniform interface has four constraints. In order to understand uniform interface, we need to understand these constraints.

This states that the server can add more functionality the REST client, by sending code that can be executable by that client. In the context of the web, one such example is JavaScript code that the sends to the browser.

Let's consider an example to understand this better.

For example, a web browser acts like a REST client and the server passes HTML content that the browser renders. At the server side, there is some sort of server-side language which is performing some logical work at the server side. But if we want to add some logic which will work in the browser then we (as server-side developers) will have to send some JavaScript code to the client side and the browser and then execute that JavaScript code. So that the JavaScript code can add validation to a form, some animation or anything else, that couldn't be possible simply in HTML content. That JavaScript code is code on demand which the server sends to the client that extends the functionality of the REST client.

Note that sending code on demand to the client is optional, and not required if we don't want to extend the client's functionality.

This constraint states that the REST system can multiple layers and if a is requesting for a response and getting a response, it can't be differentiated if it was returned from the server or another middle-ware server. So if one server layer is replaced by an other, it doesn't affect the client unless it provides what it is expected to provide. In short, one layer doesn't have knowledge beyond the next layer with which it is interacting directly.

RESTful web services are on RESTful resources. A RESTful resource is an entity/resource that is mostly stored on a server and that client request using RESTful web services. Here are a few characteristics of a resource in terms of RESTful web services:

If you are still wondering what exactly is a resource, consider the example of a blog. In a blog system, a Post, User, Category, or Comment can be a resource. In a shopping cart, a Product, Category, or an Order can be a resource. In fact, any entity which a client is requesting from the server is a resource.

Most commonly, there are five typical operations which can be performed on a resource:

For each operation, we need two things: the URI and HTTP method or verb.

The URI contains a resource name that is a noun and the HTTP method that is a verb. To perform some operation on an entity, we need to have a noun that tells us which entity we need to perform some operation. We also need to specify a verb to tell us what operation we want to perform.

For the preceding mentioned operations, there is a URL convention that we use with HTTP verbs and resource names. In the next section, we will review the URL structure and HTTP verbs for each operation.

Here is how these operations be performed a resource a combination of URIs and HTTP verbs. Note, in the following mentioned operation's URIs, you to replace {resource} with a resource name.

One old alternative to REST is SOAP. In fact, SOAP was already, used REST came along as an alternative. A key difference is that SOAP doesn't have some particular convention that tells consumers how to access that. SOAP exposes its services using WSDL. Consider WSDL as a definition of that SOAP provides. This is how the consumer knows what SOAP based web service provides and how to consume them.

On the other hand, REST emphasizes on "c

Other than that, simplicity of statelessness, separation of concerns, and cache-ability are some of the other advantages of RESTful web services that we have already seen in detail.

HTTP methods can be both safe or unsafe. By safe, it means the methods not expected to any resource on the server and by unsafe it means the are expected to change resource on the server. So this way, we have GET as the only safe method, as it is not expected to change anything on the server while other methods such as PUT, POST, PATCH, and DELETE are considered as unsafe methods since they are expected to do some changes on the server.

There are methods which achieve the same results matter how many time repeat the same operations. We consider GET, PUT, PATCH, and DELETE as idempotent methods, as no matter how many times we repeat these method calls, it will always result in the same thing. For example, if you are using GET example.com/books , it will always return the same list of books, no matter how many times you call this URL with the GET method. However, if user put something else in database then it can have different result in listing but to declare some method idempotent or not, we are not considering change in result because of external factors instead of that method call itself. In the same way, if you use PUT or PATCH, let's say PATCHexample.com/books/2?author=Ali, it will always result in the same response no matter how many times you call this method with the same parameters.

The same is the case with DELETE. It doesn't matter many times you call DELETE on the resource, it will only be deleted once. However, for DELETE, it can vary based on the implementation as well. It is something that depends on how you as a programmer want to implement. You probably want to DELETE and give a successful response the first time and on subsequent calls. You can simply give 404 because the resource no longer exists.

POST is non-idempotent because it creates a new resource on the server and the response has at least one unique attribute (mostly that is the ID of the resource), even if all the other attributes are same in the case of the same request parameters.

Until now, we have understood RESTful web services conventions, URL patterns, HTTP methods, and the nature of HTTP methods. However, it was mostly about requests. The URL and HTTP method are both request-related points. We haven't yet looked at responses, so now let's take a look into that.

In the current world, many people think that the of a RESTful web service be a JSON or text having a JSON string. However, we can also use XML in response to a RESTful web service request. A lot of people use JSON in response because it is lightweight and easy to parse. But at the same time, this is just a matter of preference, and depends on the requirement and has nothing to do with REST standards.

Both XML and JSON are ways to format data. XML stands for Extensible Markup Language, having markup syntax. While stands for JavaScript Object Notation, with JavaScript object-like syntax. For more understanding of JSON, please check out http://www.json.org/

We will shortly look into the case study of a blog and will see request and response examples. In this book, will use JSON as the response type, as JSON is simpler than XML. And while developing new applications, we mostly use JSON because it is lightweight and easy to understand. As you can see in the following examples, the same data in JSON is much simpler than XML and only has content that matters.

Here, we are trying to show the data of books having one or more authors:

XML:

<books>
  <book>
    <name>Learning Neo4J</name>
    <authors>
      <author>Rik Van Bruggen</author>
    </authors>
  </book>
  <book>
    <name>
     Kali Linux – Assuring Security by Penetration Testing
    </name>
    <authors> 
      <author>Lee Allen</author>
      <author>Tedi Heriyanto</author>
      <author>Shakeel Ali</author>
    </authors>
 </book>
</books>

Now, let's look at the same example in JSON:

{
books: [
  {
    name:"Learning Neo4J",
    authors:["Rik Van Bruggen"]
  },
  {
    name:"Kali Linux – Assuring Security by Penetration Testing",
    authors:["Lee Allen", "Tedi Heriyanto", "Shakeel Ali"]
  }
 ]
}

You can clearly see from the preceding example, that XML and JSON both convey the same information. However, in JSON it is much easier as well as it needs a lot less words to show the same information.

Hence in the rest of book, we will be using JSON as the response type of our RESTful web services.

Response codes, better known as HTTP status codes, tell us about the status of a request. If an HTTP request is successful, the HTTP status code is 200 which means OK. If there is a server error, it returns 500 status code which means an internal server error. In case of any problem in the request, the HTTP status code is 400 and onwards where 400 status code means a bad request. In case of redirection, the response code is 300 and onwards.

To see complete of response and their usage, see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

I won't go into details of it as it would be redundant since all of it is already available at the preceding mentioned Wikipedia link. However, we will discuss the different status codes as we proceed.

Here, we are listing the requirement a blog post its endpoints. For those endpoints, we will write a request and a response.

{id:1, title:"Awesome Post", content:"This is an awesome post", link: "/posts/1" }

{id:1, title:"Awesome Post", content:"This is an awesome post", link: "/posts/1" }

{id:1, title:"Modified Post", content:"This is an awesome post", link:"posts/1" }

{success:"True", deleted_id:1 }

{
data:[
  {
   id:1, title:"Awesome Post", content:"This is an awesome post", link: "/posts/1" 
  },  
  {
   id:2, title:"Amazing one", content:"This is an amazing post", link: "/posts/2"
  }
 ],
total_count: 2,
limit:10,
pagination: {
    first_page: "/posts?page=1",
    last_page: "/posts?page=1",
    page=1
 }
}

Here, we are listing the requirements of a post comment and its endpoints. For those endpoints, we will write Request and Response.

{id:1, post_id:1, comment:"An Awesome Post", link: "/comments/1"}

{id:1, post_id:1, comment:"An Awesome Post", link: "/comments/1"}

{id:1, post_id:1, comment:"Modified Awesome Comment", link: "/comments/1"}

{success:"True", deleted_id:1 }

{
data:[
  {
   id:1, comment:"Awesome Post", post_id:1, link: "/comments/1" 
  }, {
   id:2, comment:"Another post comment", post_id:1, link: "/comments/2"
  } 
 ], 
 total_count: 2,
 limit: 10,
 pagination: {
 first_page: "/posts/1/comments?page=1",
 last_page: "/posts/1/comments?page=1",
 page=1 
 } 
}