Codeeta API v1.0

Introducción

La API v1.0 de Codeeta ha sido diseñada para que puedas aprovechar los servicios y capacidades cloud de nuestro servicio desde tus propias aplicaciones. Queremos ir mejorando sus capacidades con tus sugerencias, así que anímate a probarla y cuéntanos que echas en falta para poder sacarle todo el partido en tu aplicación.


¿Qué estructura tiene la API de Codeeta?

La API de Codeeta está accesible a través de la URL https://api.codeeta.com y al interaccionar con ella devuelve resultados en formato JSON. Se trata de una API REST que permite ordenar acciones de lectura y escritura a través de mecanismos GET, POST, PUT y DELETE debidamente autenticados mediante el correspondiente API Key.

Su estructura tiene tres bloques principales: la URL de la API, el API Key de autenticación y la acción de la API que queremos ejecutar.

Estructura de la API

Para utilizar el API de Codeeta necesitarás conocer tu API Key e identificar los widgets y elementos del widget con los que quieres interactuar. En los siguientes apartados te explicamos cómo obtener esta información y cómo realizar una sencilla interacción con la API.


¿Cómo averiguar tu API Key?

Para descubrir tu API Key debes iniciar sesión en Codeeta, pulsar en el enlace “Tu cuenta” y a continuación en la pestaña “API” que aparece en el submenú.

API key de Codeeta

Tu API Key es el código único de 32 caracteres que aparece identificado como token de autorización. Este código único permite el acceso a tus datos, por eso debes mantenerlo en tu propiedad y no revelarlo nunca a terceros.


¿Cómo identificar un widget concreto?

Todos los widgets de Codeeta son identificados mediante un código numérico único. Para averiguar el identificador del widget con el que quieres interactuar, debes pulsar en el enlace “Ver widget” que aparece en el listado principal de widgets y fijarte en el último segmento de la URL donde se muestra el widget.

Visualizar widget

El identificador del widget es el código numérico que aparece en la URL tras la última barra del navegador.

Identificador widget

¿Cómo identificar un elemento concreto del widget?

Al igual que ocurre con los widgets, todos los elementos que componen un widget de Codeeta (título, párrafos, campos de entrada, campos de selección,…)  son identificados mediante un código numérico único. Para averiguar el identificador del elemento con el que quieres interactuar te recomendamos utilizar Firebug. Firebug es un complemento gratuito y esencial para el navegador web, que utilizamos todos los que trabajamos en Internet para poder identificar el código fuente (HTML), estilos (CSS) y comportamiento (Javascript) de una página web.

Identificador del elemento

Al añadir Firebug como complemento para tu navegador, aparecerá su icono en la esquina inferior derecha de la pantalla, si no llegas a verlo pulsa la tecla F12 para habilitarlo.  Al pinchar sobre el icono para abrirlo y situarte en su pestaña de detección de HTML te mostrará el HTML de cualquier elemento sobre el que te sitúes en la página web principal o en nuestro caso el widget. Los elementos que componen un widget de Codeeta son elementos <li> de una lista ordenada <ol>. Cada uno de ellos tiene un id que incluye el código numérico único que lo identifica.

Otra forma de obtener los identificadores de los elementos de un widget concreto es con la siguiente llamada a la API de Codeeta: https://api.codeeta.com/api_token/widgets/widget_id


¿Qué puedo hacer con la API de Codeeta?

En esta primera versión, la API de Codeeta ofrece su funcionalidad en dos bloques principales: lectura y escritura.


¿Cómo interaccionar con la API?

A continuación mostramos un ejemplo del código necesario para interaccionar con la API de Codeeta utilizando PHP. En este ejemplo añadiremos una respuesta a un formulario de contacto, creado en Codeeta y que mostramos a continuación, y posteriormente la leeremos.

Paso 1.
Averiguamos nuestro API Token: af3c9a078b89396016c42281c210f868

Paso 2.
Averiguamos el ID del widget con el que queremos interaccionar: 19805

Paso 3.
Averiguamos los IDs de los elementos del widget:

  • Nombre ->150612
  • Email -> 150614
  • Teléfono -> 150615

Mostramos a continuación las tres interacciones con la API: un POST para escribir una nueva entrada, un GET para obtener un listado de entradas y un GET para obtener el detalle de una entrada concreta.

Paso 4a. Escritura de una entrada.

Implementamos con PHP una llamada a la API que realiza un POST a https://api.codeeta.com/widgets/responses/add con los siguientes parámetros:

  • API Token: af3c9a078b89396016c42281c210f868
  • widget_id: 19805
  • element_responses:
    • 150612 -> ‘Ramón Jiménez’
    • 150614 -> ‘ramon@jimenez.com’
    • 150615 -> ’123456789′

Paso 4b. Lectura del listado de entradas recibidas.

Implementamos con PHP una llamada a la API que realiza una petición GET a https://api.codeeta.com/api_token/widgets/widget_id/responses/list con los siguientes parámetros:

  • API Token: af3c9a078b89396016c42281c210f868
  • widget_id: 19805

Paso 4c. Lectura de una entrada concreta.

Implementamos con PHP una llamada a la API que realiza una petición GET a https://api.codeeta.com/api_token/widgets/widget_id/responses/response_id con los siguientes parámetros:

  • API Token: af3c9a078b89396016c42281c210f868
  • widget_id: 19805
  • response_id: TY019805-00000001