Este proyecto implementa una API REST para gestionar listas de contactos en nombre de distintos usuarios.
Se trata de un proyecto educativo para dar apoyo a clases sobre desarrollo de clientes de APIs REST.
El proyecto consta de:
- bd/api_contactos.sql: script de creación de la base de datos MySQL
- include: Archivos de cabecera/pie para las páginas visibles
- lib: Funciones de uso general
- modelos: Clases de modelo y acceso a datos
- En bd.php se deben configurar los datos de conexión a la BD
- Páginas de UI:
- index.php: Página principal de introducción y documentación
- registro.php: Página de formulario para crear una clave de API
- registroSubmit.php: Página de procesado del formulario
- Endpoints de API:
- login.php: Recibe un usuario y contraseña y devuelve una clave de autorización para usar las operaciones de API
- cuenta.php: Permite consultar, crear y modificar cuentas de usuario
- contactos.php: Permite consultar, crear, modificar y borrar contactos de un usuario
Para empezar a usar esta API necesitas una clave que tendrás que incluir en la cabecera X-ClaveApi de todas las llamadas que realices.
Los desarrolladores que quieran usar la API pueden crear una clave de API en el formulario de registro de clave API
ATENCIÓN: La página de registro de claves API no tiene ningún mecanismo de seguridad y cualquiera puede crear una clave de API. Si publicas esta API es recomendable vigilar que las claves creadas pertenecen a los usuarios previstos y borrar los datos periódicamente.
En la mayoría de operaciones de la API, se necesita incluir la cabecera X-Auth con la clave de autorización de una cuenta de usuario.
Las cuentas de usuario constan de los siguientes campos:
- nombre: Nombre completo del usuario
- email: Dirección e-mail
- pwd: Contraseña
- authkey: Clave de autorización (valor autogenerado)
Las cuentas de usuario se crean con la operacion POST cuenta.php indicando el nombre, email y pwd. La operación devuelve el usuario completo, incluyendo un nuevo authkey.
Cuando un usuario quiera acceder a tu app, utiliza la operación POST login.php para obtener su clave de autorización a partir de su e-mail y contraseña.
Si ya tienes el authkey de un usuario, puedes consultar sus datos con la operación GET cuenta.php o modificarlos con PUT cuenta.php
Los contactos tienen los siguientes campos:
- idContacto
- nombre
- telefono
- direccion
- notas
Puedes consultar, añadir, modificar y borrar contactos con las siguientes operaciones:
GET contactos.phpDevuelve la lista de contactosPOST contactos.phpAñade un contactoGET contactos.php?id=123Devuelve los datos del contacto 123PUT contactos.php?id=123Modifica los datos del contacto 123DELETE contactos.php?id=123Borra el contacto 123
Si hay algún error en la petición, se devuelve un código de error HTTP 4XX y el texto del mensaje de error en el cuerpo de la petición (sin codificar en JSON)
400- Sin cabecera X-ClaveApi
No se ha incluido la cabecera X-ClaveApi
400 - Cabecera X-ClaveApi no válida
El valor de la cabecera X-ClaveApi no es válido o no existe en la BD
400 - Sin cabecera X-Auth
No se ha incluido la cabecera X-Auth y la operación lo requiere
400 - Cabecera X-Auth no válida
El valor de la cabecera X-Auth no es válido o no existe en la BD
La página index.php muestra la documentación completa para los usuarios que vayan a utilizar la API.
Acceso de usuario. No requiere cabecera X-Auth.
Petición
{
"email": "[email protected]",
"pwd": "123456"
}
Respuesta
{
"auth": "4ef...76c"
}
Errores
- 400 - Usuario o contraseña incorrectos
Crear usuario. No requiere cabecera X-Auth.
Petición
{
"nombre": "Usuario",
"email": "[email protected]",
"pwd": "123456"
}
Respuesta
{
"idUsuario": 1,
"nombre": "Usuario",
"email": "[email protected]",
"pwd": "XXX CIFRADA XXX"
"auth": "4ef...76c"
}
Errores
- 409 - Ya existe un usuario con el mismo e-mail
Obtiene los datos del usuario correspondiente a la X-Auth
Respuesta
{
"idUsuario": 1,
"nombre": "Usuario",
"email": "[email protected]",
"pwd": "XXX CIFRADA XXX"
"auth": "4ef...76c"
}
Modifica los datos del usuario correspondiente a la X-Auth.
Si no se indica pwd, se mantiene la que hay
Petición
{
"nombre": "Usuario Modificado",
"email": "[email protected]",
"pwd": "12345678"
}
Respuesta
{
"idUsuario": 1,
"nombre": "UsuarioModificado",
"email": "[email protected]",
"pwd": "XXX CIFRADA XXX"
"auth": "4ef...76c"
}
Errores
- 409 - Ya existe un usuario con el mismo e-mail
Obtiene la lista de contactos del usuario.
Respuesta
[
{
"idContacto": 123,
"nombre": "Contacto 123",
"email": "[email protected]",
"telefono": "12345678"
"direccion": "C/ Mayor 5"
"notas": "Amigo del trabajo"
},
{
"idContacto": 234,
"nombre": "Contacto 234",
"email": "[email protected]",
"telefono": "666555444"
"direccion": "Pza España 12"
"notas": "Cumpleaños 12 de junio"
},
...
]
Crear contacto
Petición
{
"nombre": "Contacto Nuevo",
"email": "[email protected]",
"telefono": "654321987"
}
Respuesta
{
"idContacto": 567,
"nombre": "Contacto Nuevo",
"email": "[email protected]",
"telefono": "654321987"
"direccion": ""
"notas": ""
}
Obtiene los datos del contacto con el id indicado
Respuesta
{
"idContacto": 123,
"nombre": "Contacto 123",
"email": "[email protected]",
"telefono": "12345678"
"direccion": "C/ Mayor 5"
"notas": "Amigo del trabajo"
}
Errores
- 404 - El contacto no existe o no pertenece al usuario
Modificar contacto
Petición
{
"nombre": "Contacto 123 modificado",
"email": "[email protected]",
"telefono": "654987321"
"direccion": "",
"notas": "Cuenta instagram: @contacto123"
}
Respuesta
{
"idContacto": 123,
"nombre": "Contacto 123 modificado",
"email": "[email protected]",
"telefono": "654987321"
"direccion": "",
"notas": "Cuenta instagram: @contacto123"
}
Errores
- 404 - El contacto no existe o no pertenece al usuario
Eliminar contacto
Errores
- 404 - El contacto no existe o no pertenece al usuario