Tutorial Sobre Como Crear Tu API

Bien, esta vez sí, a petición del público y con retraso (perdón por la espera, pero ando muuy liado) intentaré explicar las bases para que uno por sí sólo pueda crear una API para su sitio web.

¿Que es una API?

Una API o Application Programming Interface es un grupo de funciones que permiten que desarrolladores puedan acceder a tus datos, de tal forma que puedan comunicarse con la base de datos sin necesidad de disponer del código fuente de nuestro sitio.

Sin ir más lejos Windows dispone de una API para que las empresas desarrollen software para su sistema operativo. Los pioneros en lanzar API’s en internet creo que fueron Amazon y eBay.

¿Para que sirve una API?

Las APIs son una herramienta perfecta para poder extender tu aplicación más allá de tu sitio web y crear aún más comunidad alrededor de tu marca. Una buena API puede permitir a nuestros usuarios que creen Mashups con tus datos cruzados con otros y de esta manera acceder a mucho más gente de la que nuestro site pueda abarcar.

El ejemplo más claro es Twitter que con su API ya se han creado más de 6000 sitios en toda internet que disponiendo de los datos de los usuarios de twitter pueden crear multitud de aplicaciones para ayudar o añadir valor al servicio. Sin duda todo un éxito.

Empecemos a Construir Nuestra API

Digamos que nuestra API puede disponer o no de dos grandes funcionalidades:

• Recojer y disponer de los datos de nuestro sitio para mostrarlos de la forma conveniente
• Alterar esos datos, cosas cómo modificar datos, añadir nuevos o eliminarlos.

Si la API que queremos contruir no necesita de autentificaión para usarla, las llamadas API Keys, puede ser una buena solución que nuestra API se comunique mediante el servidor usando GET y la url, así pues una consulta para eliminar el articulo numero 5 sería algo cómo:

http://misitio.com/api/borrar/5

Pero si son muchos los parámetros a enviar o creemos que nuestra API debe disponer de algo de seguridad para poder ser usada la mejor opción va a ser escoger el método POST. Este sistema nos va a permitir comprobar antes de empezar a procesar la información que la petición tenga los permisos correctos.

SOAP vs REST

Hay dos tipos de APIs usadas para en cuanto a web nos referimos. Google por ejemplo usa SOAP y Yahoo usa REST, vamos a ver que es cada cosa:

• API’s con REST: Se basan en llamadas HTTP mediante URI y el formato de la respuesta la podemos definir nosotros. Normalmente las APIs con REST són más rápidas y fáciles de implementar.
• Las APIs con SOAP suelen ser un poco más complicadas y necesitan la instalación de un plugin dependiendo del lenguaje de programación que estemos usando, en PHP o Python por ejemplo es necesario. Las APIs con SOAP se asemejan más a un sistema de métodos, así, para hacer la misma llamada que antes haciamos mediante URI (usando REST), en SOAP sería algo cómo:

  $api->borrar(5)

Nosotros en este caso y aclarando desde un principio que esto es una inicición y un primer enfoque a cómo debería construirse una API y cuales son nuestras opciones, usaremos REST para este post.

Código y Lo Que Ya Debemos Tener

En este ejemplo doy por supuesto que disponemos de una clase que nos permite interactuar con la base de datos y devolvernos datos, algo como:

class Data {

private $id;

function _construct($id){
$this->id = $id;
}

function borrar($id){
mysql_query("DELETE * FROM articulos WHERE id = '$id'");
// etc.. etc..
}

}

En nuestro server haríamos lo siguiente:

include 'class/class.Data.php';
$obj = new Data();
$obj->borrar(5);

Genial hasta aquí, pero cómo lo hacemos para alguien que no tiene acceso a nuestro servidor?
Debemos crear una especie de interfaz entre el usuario y nuestra classe, entonces nuestro archivo alojado en ‘api/borrar.php’ queradía así:

include '../class/class.Data.php';
if(permiso( $_POST['api_key'] )){
$obj = new Data();
$obj->borrar(5);
}

Eso va a permitir a nuestros usuarios de la API que envien consultas POST al archivo ‘api/borrar.php’ y si la clave es la correcta le permitiremos hacer la acción. Entendemos que la función permiso() debe comprobar que esta clave esta aceptada dentro de nuestra base de datos.

La Petición

Para realizar la petición HTTP vamos a usar cURL de PHP que va genial y es muy fácil de usar sencillamente necesitamos definir la URL que vamos a llamar y los parametros de la llamada:

// definimos nuestras variables POST
$post_vals = array(
    'api_key' => '0123456789',
    'id' => '5'
);

foreach($post_vals as $key => $value) {
    $peticion .= $key.'='.urlencode($value).'&';
}

$peticion = rtrim($peticion, '&');

$ch = curl_init('http://misitio.com/api/borrar.php');
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $peticion);
$respuesta = curl_exec($ch);
curl_close ($ch);
);

La Respuesta y su Formato

Cómo nos lo vamos a hacer para dar la respuesta a la petición? Hay varias maneras, las más conocidas son mediante XML o JSON, el consejo es que si puedas ofrezcas las dos formas.

Otra cosa a tener en cuenta y no olvidar es dar las respuestas a los procesos si todo ha funcionado correctamente o si ha fallado alguna cosa, para que el usuario final sea capaz de poder crear una pequeña función isSuccess() etc…

Un ejemplo de respuesta en XML podria ser:

<respuesta estado="ok">
<metodo>borrar</metodo>
<formato>rest</formato>
<id>5</id>
<api_key>01234567890</api_key>
</respuesta>

Disclaimer: Todo el post esta explicado sobre el método borrar, aunque si hacemos un ejercicio de refleción pronto nos daremos cuenta que un método de estos sólo nos puede perjudicar!

Links de interés

• http://www.gen-x-design.com/archives/create-a-rest-api-with-php/
• How to Design a Good API
• cURL en PHP.net
• SOAP y REST en la Wikipedia

Tagged as: api, classes, PHP, rest, soap, Tutoriales, xml