Technical note book of Chatura Dilan

PHP Data Services – Tutorial Part II (Creating APIs)

In our first tutorial we created a Data Service (Data App) for the ‘Tourism’ system. If you haven’t done the first tutorial, it is a must to complete the first tutorial before continue this tutorial. You can access the first tutorial form this link http://technotes.dilan.me/?p=116

Data APIs
After creating Data App, Data APIs can be created for a particular Data App. Data APIs can be versioned security can be applied for each Data Collection in a Data App. There are four types of security mechanism. WADL (Web Service Description Language) can be generated from Data APIs

i. Private – This makes the data collection inside data API private and can be access by none.
ii. Public – This makes the data collection inside data collection of API public for all.
iii. Secret- An secret key can be added to secure the data collection of APIs
iv. Social – Social network connection Authentication can be added to secure the data collection API

1. Now we are going to create an API for the data app we have created in the tutorial 1.  Click on ‘Data Apps’ Tab and select your ‘Tourism’ Data App. Click on the APIs link and you will see all the APIs which associate with the Data App you have selected (initially list is empty). Click on ‘Add’ button to create the API. enter details as following image. Please leave Enable Analytics for unchecked now.screenshot19

Save the API. That’s it you have just created a API for the Data App. But initially all Data Collection associated with the current API is private.

Go to API list  and Click on GoInto link

screenshot20

screenshot21

2. As the above screen you can see all the auth types of our Data Collection are set to private. Now we need to add following Authentications for our Data Collections

i. Tourism Public Service – Authentication Type Public (Since this is a public API anyone can be able to access to this API)

ii.Tourism Admin Service – Authentication Type Secret (Since this is a admin API which is used in the backend we can protect it with a strong secret key)

iii.Tourism User Service – Authentication Type Social (Users need to login through Facebook to access this API)

3. Now select Tourism Public Service Data Collection and click Edit. Please set the Auth type to public and save it.

You can access your APIs from following URL pattern. As an example if you want to access your public API cities use

<Your host>/services/api/<Data App name>/<API Name or Version>/<Data Collection name>/<Table name>

Eg: http://localhost/datas/services/api/tourism/v1/tourism-public/cities Will shows all the cities. Since this a public API no secret key needed.

screenshot23

4. Now select Tourism Admin Service Data Collection and click Edit. Please set the Auth type to secret, provide a strong secret key and save it.

screenshot22

5. Now it is the interesting part to provide API security for users. First of all we need to create an Facebook app for this purpose.

To create a Facebook app go to Facebook and go to Facebook Developer App and click on New App. Once you created the Facebook app you will get the App Id and App Secret from Facebook

screenshot24

screenshot25

6. Download PHP Data Service Hybrid Auth App from the GitHub. You can get it from here https://github.com/chaturadilan/PHP-Data-Services-Hybrid-Auth-Plugin/releases/tag/v1

Copy the auth1 (you can rename this folder to any name, but please make sure to use that name when accessing it. you can add multiple auth folders to auth folder as well) folder to PHPDS /app/webroot/auth folder.  Now access the auth folder by following link in the url

<Path to PHPDS>/auth/auth1/hybridauth/install.php

Eg:  http://localhost/datas/app/webroot/auth/auth1/hybridauth/install.php

Please make sure /app/webroot/auth/auth1/hybridauth/config.php is writable.

7. Copy the HybridAuth Endpoint URL and paste it in Website with Facebook Login -> Site URL and Save Changes.screenshot27

8. Enable the Facebook Adapter Satus and Add Facebook App Id and App secret. Disable other social networking Adapters, and click ‘Setup HybridAuth’ button at the bottom. Please remove the install.php file after setting it up for security reasons.

screenshot26

9. Now you need to set database settings for Hybrid Auth app. open app/webroot/auth/auth1/app/sign/application.config.php change the database setting which match with your tourism database


// database config
 $database_host = "localhost";
 $database_user = "root";
 $database_pass = "";
 $database_name = "tourism";

10. Now go back to PHPDS -> Tourism Apps -> APIs -> Go Into and select ‘Tourism User Service’ click Edit and Select Security Type as social. Select the Auth App as auth1, and enter user_id for identifier ( Identifier is automatically added as a parameter after user is login to the system. It is taken from the current session. Identifier is current user’s id. We are using the auth to update comments form the user. In our comment table, there is a column called user_id. It is automatically updated with current user id. Click Save.

screenshot28

11. Congratulations!! Now you have created your first Data API with security. Let’s test it.

First let’s test the Public API. Here I’m using a Firefox add-on called REST client to send requests to our API

As I describe above here is the URL pattern to access the API for CRUD methods

<Your host>/services/api/<Data App name>/<API Name or Version>/<Data Collection name>/<Table name>

Here is the pattern for custom methods

<Your host>/services/api/<Data App name>/<API Name or Version>/<Data Collection name>/<Method alias>/<Method name>

12. Here we are sending a GET request to http://localhost/datas/services/api/tourism/v1/tourism-public/cities

screenshot29

13. Let’s test the admin API by adding a new city to the database. To add a new city we need to send a POST request to http://localhost/datas/services/api/tourism/v1/tourism-admin/cities followed by the secret key we defined. So that our URL will be

http://localhost/datas/services/api/tourism/v1/tourism-admin/cities?secret=1234THISISADMINAPI321

and we need to send following in the request body. Please make sure to add a  request Header called Content-type which is set to application/json (which is not shown in the image))

{
"name" : "Kalutara",
"province_id: "1"
}

And the output is

screenshot30

14. Now let’s test the user api. To login to Facebook goto http://localhost/datas/app/webroot/auth/auth1/app/sign/index.php?route=users/login and select Sign-in with Facebook.

screenshot31
Please add the Facebook App to your profile.
screenshot32

screenshot33

Once you successfully logged in you will get the following page. Please check users and authentication tables and you can see there is a record for the newly registered user.

screenshot34
Now let’s test our user API by adding a comment. we need to send a POST request to http://localhost/datas/services/api/tourism/v1/tourism-user/comments

The body request would be. Please make sure to add a  request Header called Content-Type which is set to application/json (which is not shown in the image))

{
"comment" : "Great city! Love it",
"city_id: "1"
}

screenshot35

That’s it you can see your newly added comment as the table record, and the user_id is set to the logged in user id which is 1.

15. When you publish the app, please uncheck the Sandbox mode of the Data App. In our next tutorial let’s see how to add Google Analytics to our APIs http://technotes.dilan.me/?p=220


3 thoughts on “PHP Data Services – Tutorial Part II (Creating APIs)

  1. Thank you! This is great and everything seems to have been set-up fine.

    One problem I noticed is that when I post a comment update that in the comment table a new record is added but the comment and city_id fields are not populated.

    Any suggestions on where the problem might be? Also if you could please include the exact way in which I should add a request Header called Content-type which is set to application/json that would be appreciated. Not sure if I am doing it correctly.

    Thanks again for the excellent application and instructions!

    • Hi Nate,
      Sorry, there is a small spelling mistake in the blog when you setting the Content-Type, T should be capital here; not Content-type. I corrected it. In rest client select headers from the top menu and select Custom Header. Add Content-Type as the name and add application/json as the value and click Okey. Like that you can add a custom header. Hopes that helps. Good luck with PHP Data Services.

Leave a Reply

Your email address will not be published. Required fields are marked *