The Dump - Code and Beyond > myApi - simple API using curl PHP

myApi - simple API using curl PHP

# Introduction:

myAPI is a simple API using curl PHP to pull data in JSON or XML formats from a service provider to a registered client in a secure and convenient way.

# Features:

Supports get requests for any data contained in a database.
Simple query string in the client side.
e.g. https://www.your-client-site.com?where=country=italy+price<1600
Return data in JSON or XML formats.
Highly secured user authentication.
Support pagination.
Ability to track the users.
Simple installation on both the service provider side and client side.

# Query string

# Define the where part of the query:

For example, if you want to run a query for Italian hotels with price lesser than 1600.
https://www.your-client-site.com?where=country=italy+price<1600

If you want to run a query for Thai hotels or price more than 600.
https://www.your-client-site.com?where=country=thailand|price>600

# Define the format part of the query:

The returned results are JSON formatted unless the client specify an XML format.

XML format:
https://www.your-client-site.com?where=country=italy&format=xml

JSON format:
https://www.your-client-site.com?where=country=italy&format=json

# Limit the number of records:

You can limit the number of results returned from the web service. For example, if you want 12 results to be returned.
https://www.your-client-site.com?where=country=italy&num=12.

# Installation:

Inside this project's examples folder you will find two sub folders:

server_side - The content of this folder should be placed in the service provider's site.
client_side - The content of this folder should be placed in your clients' sites.

# Service provider side:

Inside your-site/path/to/myApi/src/config/init.php define the database credentials in the $config array.
In your database, run the 'myapi_auth.sql' file to create the table to authenticate the users.
Add users to the 'myapi_auth' table, with both their key and password SHA1 encrypted.
In the 'index.php' file fill the following variables:
- $tableName - The table name to return the results from. mandatory
  e.g. $tableName='hotels';
- $fields - The array of fields in the table to query from. mandatory
  e.g. $fields=array('name','date','price');
- $orderBy - The array to build the orderBy clause from
  e.g. $orderBy=array('price','asc');
- You may also fill the arrays $tableNameAlias and $fieldsAliases to provide your users with different table and fields names than those in the database.

# Client side:

For each and every distant client you need to create key and password (see the 2nd and 3rd items in the service provider side).
Provide to your clients the index file from the client_side folder, with the following mandatory variables:
- $clientKey - Unhashed client's key
- $clientPass - Unhashed client's password
- $url - The url to the api folder in the service provider site.
  e.g. $url='https://client-side-site.com/myApiFolder';
The minimal data requests from the client's side should contain a where clause. For example, if you provide data about hotels the request may look like the example below:
https://www.your-client-site.com?where=country=italy+price<1600
- format - json or xml.
- num - Maximum number of records to return.

# Database:

# Database configuration:

In order to configure your database connection, edit the database credentials in:
your-site/path/to/myApi/src/config/init.php.


/**
 * Define your database credentials here.
 */
$config = array(
  'database' => array(
    'driver'   => 'mysql',
    'host'     => '127.0.0.1',
    'name'     => '',
    'username' => '',
    'password' => ''
  )
);

# Define table and fields:

Define the database table and fields to query from in:
your-site/path/to/myApi/index.php.

For example, if you want to run a query on a table named 'hotels' and would like to return the fields: name, price and date.


// The name of the table to pull results from.
$tableName = 'hotels';

// The name of fields in the table to pull results from.
$fields    = array('name','price','date');

# Define the order of results:

You can define the order of results with the values: 'asc' for ascending order or 'desc' for descending.
For example, if you want to order the results by price, you can change the $orderBy array in:
your-site/path/to/myApi/index.php.


$orderBy = array('price','asc');

# User authentication:

# The 'myapi_auth' database table:

In your database, run the 'myapi_auth.sql' file to create the table to authenticate the users against.
The table has the following fields:

key - The hash1 encrypted client key.
pass - The hash1 encrypted password.
active - 0 or 1.

# Distant client authentication:

Provide each user a unique user-key and user-password to authenticate his identity. The key and password you provide to the user should be unhashed and match the hashed values in the myapi_auth table.

The credentials should be written into the client index file in:
your-client-site/path/to/myApi/index.php.

For example, if you provide your client the key '1234' and password 'pass123'.


// Unhashed user key from authentications table.
$clientKey  = '1234'; 
// Unhashed unique user password from authentications table.
$clientPass = 'pass123';

# Output considerations

It is highly advisable to use different names for the output than the names you use in your database for the table and fields names in order to prevent breakage whenever you change the names of the table or fields in your database and for security reasons.

In order to change the outputted table name fill a replacer string in the $tableNameAlias in: your-site/path/to/myApi/index.php.

In order to change the outputted fields names fill the $fieldsAliases array with a replacers for the fields names in:
your-site/path/to/myApi/index.php.

# Pagination

Pagination allows the user to divide the data returned to him into pages, that the user can paginate between. For example, the next query specifies the page number (the 'page' part of the url) and the number of results per page (the 'num' part of the url):
https://www.your-client-site.com?where=country=italy+price<1600&page=1&num=10

You have to call for the methods that enable the pagination in:
your-site/path/to/myApi/index.php (see the examples folder).


// Query the database for the selected data.
$posts  = new MyApi\Posts();
 
$posts->create($tableName,$fields,$_POST['where']);
 
// Optional 1: set the maximum number of records to return.
if(isset($_POST['num']))
  $posts->setNum($_POST['num']);
   
// Optional 2: set the pagination and the page number.
if(isset($_POST['page']))
  $posts->setPage($_POST['page'])->setPagination();

# Track your users

You can track the number of views and last visit date for each user. For this aim, run the 'myapi_watches.sql' file to create the table that tracks your users views.

You have to call for the methods that update the number of views in:
your-site/path/to/myApi/index.php (see the examples folder).


// Check if the user is authenticated according to his user-key and password.   
$auth = new MyApi\Auth();
 
$userId = $auth->isAuth($_POST['key'],$_POST['pass']);
 
 
// Option: Update the number of watches for the user.
$watch = new MyApi\Watch();
 
$watch->updateWatches($userId);

# Request lifecycle

The client sends his request with a where string.
e.g. https://www.your-client-site.com?where=country=italy+price<1600
The request is processed in the client side and sent to the service provider through post curl with the client's credentials and request.
The clients credentials are checked against existing users in the database.
If the request is valid, the user receives the results back in a JSON or XML format.