About
Define some endpoints and get your app running!
Version: 1.0.1
Author: Andrés Zorro <zorrodg@gmail.com>
GitHub: http://github.com/zorrodg/php_apihandler
Due to web technologies in constant change, and the growing popular use of Front End technologies such as Backbone, Ember and AngujarJS, the need for server side MVC frameworks that render HTML templates has become increasingly obsolete, and API endpoints to get data from has become a major need.
Just to think about installing CodeIgniter, Laravel, even Slim to deal with simple database calls and no HTML display, made me think about a better solution. I know that there are services that deal with APIs, but my needs (and for many other developers I suppouse) require full control over the data I am sending and storing. That's why I developed PHP API Handler.
The idea behind API Handler is to make it simple to develop API endpoints throught PHP. You define some Getters, Posters, Deleters and that's it. API Handler does all the heavylifting (Database queries, identify resources, encode to json or xml and output).
Currently API Handler works with MySQL and outputs to JSON and XML formats. It's intended to support more database engines and more output formats. Coming soon...
There's still a lot to do!
If you want to help developing this code, there's a lot of room for improvement. Just make a pull request and work on one of the following items:
- Improve API security overall
- Add support for OAuth 2.0 server authentication
- Add support for other Database Engines. Currently supporting MySQL only :(
- Add support for other Outputs. Currently supporting JSON and XML
Enjoy!
If you want to thank me, I won't mind accepting a beer. :)
Options Reference
Here's a list of all options that could be set to each endpoint, with explained examples.
This options refer to the array of options that could be passed to each defined endpoint. Here's an example on where this options should be:
new Getter("users", array(<options here>), TRUE);
new!
after (function)
Set a custom callback fuction that executes after data retrieval. It has one parameter that is data retrieved (response).
- Example:
"after" => function($response){
foreach($response as $key => $val){
//.. Do something with the response
}
}
new!
before (function)
Set a custom callback fuction that executes before query fetch. It has one parameter that is query string to be send.
- Example:
"before" => function($query){
//.. Do something with the query string
}
cacheable (bool)
Set whether the endpoint results will be cached or not. Default FALSE.
- Example:
"cacheable" => TRUE
col_prefix (string)
Add a column prefix to the columns. If you define one, instead of looking at col_name column, it will look for {prefix}col_name.
- Example:
"col_prefix" => "aph_"
columns (array)
Define table columns in which endpoint operates. This is an array of strings. Each string has an special notation, separated by | (pipe) character.
Depending on the HTTP call, columns will define parameters for your query, i.e. you can call your endpoint with a filter: GET http://{YOUR_ENDPOINT_LOCATION}/users.json?last_name=zorro
Note: If you set create_new_table or modify_existing_table to TRUE, columns will modify database to fit this columns.
Special Notation: {column_name}|{var_type}|{var_length}|{unique}
| Parameter |
Default Value |
Description |
column_name |
Required |
The name of the column. |
var_type |
"string" |
Database column data type. Values supported int (INT), char (CHAR), string (VARCHAR), text (TEXT), bigint (BIGINT), date, (DATETIME) |
var_length |
"200" |
The length of the data accepted. (Only for int, char, bigint and string) |
unique |
"" |
Set column key to unique. |
- Example:
"columns" => array(
"first_name|string|200|unique",
"last_name|string|200",
"group_id|int"
)
create_new_table (bool)
Creates a new table in database with given endpoint name, if not exists. This option will not create a table if it exists.
Note: If you set create_new_table or modify_existing_table to TRUE, PHP API Handler automatically will create two aditional columns without prefix called id (int) and updated (timestamp).
- Example:
"create_new_table" => TRUE
description (string)
Endpoint description. Not really useful, in fact. But it could become handy whenever you want to make your API documentation ;)
- Example:
"description" => "Get all users."
join (assoc array)
Set the columns from other tables that will be joined to current query. This associative array has an special notation, with key name and string value, separated by | (pipe) character.
join option will override result from the first query with the result of the second query, returning a complex object.
You can join as many tables as you want, as long as there are columns in common with your current query.
Special Notation: {key} => {first_col}|{second_col}|{cols_to_fetch}
| Parameter |
Default Value |
Description |
key |
Required |
The name of the table that will be joined. |
first_col |
Required |
Column from the first table (primary table, if you wish) that will be associated. |
second_col |
Required |
Column from the second table that will be associated. The values fomr the first and the second must match. |
cols_to_fetch |
FALSE |
Columns that will be fetched from the second table, separated by ,. If you don't assign it, It will fetch all columns from second table (similar to show option) |
- Example:
"join" => array("groups" => "group_id|id",
"teams" => "team_id|id|team_name,team_desc"
)
limit (string)
Set a word to use as a parameter on query string to limit results number. i.e. if you set it to count, you could call an endpoint like this: http://{YOUR_ENDPOINT_LOCATION}/users.json?count=5.
- Example:
"limit" => "count"
modify_existing_table (bool)
Modifies an existing table, if exists and if it's params change. This option will modify table, if you change table names, change column names, data type or data length. If left TRUE, it will not modify existing tables if there are no changes.
Note: If you set create_new_table or modify_existing_table to TRUE, PHP API Handler automatically will create two aditional columns without prefix called id (int) and updated (timestamp).
- Example:
"modify_existing_table" => TRUE
query (string)
Set a custom query to the database. If set, custom query is used instead of the one API Handler creates.
About kvsprintf: PHP API Handler uses a modified version of vsprintf() PHP native function, that supports associative arrays. It uses a special notation for identifying array keys and values: %{array_key_name}\$k and %{array_key_name}\$v replacing {array_key_name} for coresponding array key name.
When set, query must include table prefixes in order to work. If endpoint has variable arguments, column names must be included manually and with column prefixes.
- Example 1: Endpoint ->
users
"query" => "SELECT * FROM `api_users` WHERE `%first_name\$k` = '%first_name\$v'"
- Example 2: Endpoint ->
users/:first_name
"query" => "SELECT * FROM `api_users` WHERE `aph_first_name` = '%first_name\$v'"
Notice on Example 2 column prefix aph_ is included for it to work.
show (array)
Set the columns that will be displayed. Columns not listed will be hidden. If this option is not set, PHP API Handler will bring data from all columns.
Note: If you set create_new_table or modify_existing_table to TRUE, PHP API Handler automatically will create two aditional columns without prefix called id (int) and updated (timestamp). You can show them also.
- Example:
"show" => array("first_name", "last_name")
sort (string)
Sets the column to order the results. This string has an special notation, separated by | (pipe) character. Default order is id column.
Special Notation: {column_name}|{order_type}
| Parameter |
Default Value |
Description |
column_name |
Required |
The name of the column. |
var_type |
"desc" |
The order to display. Supported values asc (ASC), desc (DESC) |
- Example:
"sort" => "first_name|asc"
new!
table_alias (string)
Set an alias name for your endpoint. table_alias will hold your table name, while it is aliased on the endpoint.
- Example:
Given this endpoint: people.json it will search for users table instead of people table, if option set.
"table_alias" => "users"
Licence
PHP API Handler is licenced under MIT Licence:
The MIT License (MIT)
Copyright © 2014 zorrodg
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
