Have you started working with vue and php phalcon, but wondering how to make these frameworks communicate with each other? In this article we will dive deep into creating API's (application programming interface) in php Phalcon. We will design these API's and program vue to call these API's using AJAX.

 

In the previous articles, I wrote on the theory, on how to get started using vue and php (phalcon). I also covered how to configure your php phlacon application with vue. In this article we will be expanding on those concepts and dive deep into passing data between these two frameworks.  

There are two ways in which one can get data from phalcon. 

One way is to get a HTML response from phalcon and the other is by using data objects. Sending an HTML response is not a scalable approach and it also defeats the purpose of having vue. On the other hand, designing your backend application with a restful API in mind, can help you design vue phalcon applications seamlessly.  

If you use AJAX and let php phalcon respond using HTML, maintaining your code will be a nightmare. Now, not only do you have to maintain HTML in vue, but you also need to make sure the HTML response you get from phalcon is compatible with vue. For most uses cases, this is just bad design and avoid using AJAX reply using HTML. 

Replying with HTML also defeats the purpose of having vue. If you have a HTML reply, would you be inserting vue elements in your phalcon HTML response so that vue can then manipulate the HTML when it receives it? It just seems too convoluted and your code will break.

But, there is a much deeper technical reason why you should not have pure HTML response from phalcon. It is got to do with how vue actually works. One of the main reasons why vue is so popular, is not just because of it's ease of use, but because of its speed. What makes it a superior framework is got to do with something called Virtual DOM. Virtual DOM is a javascript object representation of the real DOM. If your response from phalcon is pure HTML code, Vue would treat the response as a string. It won't be able to create a virtual DOM from this response. As a result you beat the purpose of using vue. 

A better approach is to use data objects for e.g JSON. JSON is a good format to use, as javascript and php support it naively. As a result, you do not have to worry if the object is semantically right as both php and javascript can write and read JSON objects. All you need to do, is plan how the JSON object should be designed and how each element needs to be interpreted.

 

There are so many advantages using this approach. One, php does not control the HTML content, controlled by vue. Vue has full control over it. If vue needs to update elements of a component, it can request data from php, and the JSON reply will allow it to populate the HTML page accordingly. If something needs to be changed, you can manipulate the JSON object without changing the HTML. Not to mention, your application is much more scalable, vue will be able to use its virtual DOM capabilities and data will be much smaller compared to an html reply.

Let us now continue building our ecommerce application. In the previous article "Integrating Phalcon, vue components and webpack with code examples", we got started setting up these frameworks. Here, we will dive deep into populating the content of our ecommerce website from a database. Let us continue from where we left of. 

Vue acts as a template for interpreting data, but the actual content will come from phalcon using specific API's . Let us start by designing RESTful API's in phalcon. Before we dive into programming the API's, it is worthwhile to spend time understanding what the API is all about and how the data should be designed

 

How should you design your API's? 

Few rules to keep in mind. 

Identify key participants -> Who is it, that is going to use this API? Is it going to be used internally or externally? For this tutorial, our API's are going to be used internally and only by vue. In many applications, you might want external stakeholders to access your API's. Depending on your application, design your API's accordingly. 

Identify your system boundaries-> Who is the API NOT for? Clearly identify who can use these API's and who cannot. Describe what is the purpose and what should be its content.. If you need to authenticate your users or clients and allow only selected users to access the API, you would need to authenticate and authorize them. If other applications would like to have access to your API's you might need to use OAuth 2.0. In this application, we don't need any authorization. Let us keep it simple.     

Identify activities -> What is the purpose of this API? Is it to read data, update data, create new data or delete data? Depending on what activity the API performs, you can name it accordingly. For each activity, you should have a API. Don't mix activities in the same API. For this application, we will only be reading data. 

Next, let us define what REST is and what it is not.

REST stands for Representational State Transfer. One thing to keep in mind is, REST is NOT a protocol. Neither are there any REST standards. On the contrary, REST is built on existing client server architecture. It helps us to design, better ways of working and communicating between client and server.  You can read more on what defines REST and it's constraints here. Now that we have some idea on how to design our API's, let us plan out how we will be structuring the data in JSON.

You might think of designing your own content or data format inside JSON. I would highly recommend not doing so. You creating your own structure is similar to you creating your own image format to see an image. You would rather use existing formats like JPEG or PNG to view an image. Similarity, when it comes to the content of your JSON files,it is better to use a standard. There are couple of standards one can choose from. 

1. Collection + JSON   

2. Hypertext Application Language (HAL)

3. The IonHypermedia Type

4. Siren

5. JSON-LD

6. JSONAPI

7. Mason

8. UBER

9. OData

10. Atom

In this article, we will structure our content using the IonHypermedia Type. It is intuitive to read and easy to structure data. Next, let us design our API functions, program these API's in phalcon and fetch it using vue. 

There are numerous ways one can write API's in phalcon. In this use case, we will create a controller specifically for API's and each controller action would correspond to the api's activity i.e. read, write delete or update. In this tutorial, we will be reading data from the database, assemble this data, write it into a JSON file and then ehco the results to vue. Vue would then read this JSON file, interpret the data and accordingly display its content in an elegant manner. 

In this ecommerce example which is about selling stunning website templates, the content of the JSON file must have information on the type of template, the template image, the cost, the author, the discount amount and the ratings. 

Information that needs to be displayed for each website template

The JSON file response would look something like this.

Phlacon being a highly customizable framework, there are various ways in which you can go about designing your API's. This git repository shows the different ways you can configure your phalcon application. 

Let us create a new controller called WebsitetemplateController.php  and create few actions in it. We can have an action for 

search: Read database for website templates

Permission: anyone 

write: Insert a new website template into the database

Permission: authorized users 

update: Update information of the template

Permission: authorized users

delete: Delete the website template

Permission: authorized users

To give access to users, we would need to update this information in our Security.php file. For this tutorial, we just want to read the data and send it to vue to display it. We will just be making use of the search action, which is accessible to anyone. 

Next, we need to fetch data from the database, organize the contents in a pretty json file and echo the file to vue. In this case, I am reading the data from a local server which stores the data in mongodb. The output from the server, is a JSON file, which we then output it back to the frontend.  

Now, when you type /websitetemplate/search on the webbrowser, the JSON file is printed.

 

We can then ask vue, to interpret the JSON file and iterate through the array.

We can look at the vue debbuger on chrome and see if the variable 'product' has the data populated. 

 

Now it is just a matter of how you want to visually display this data on the website. 

 

 

If you have any questions  or doubts, or better ideas and concepts please comment below.