API Rest
Desde toba 2.5 se reemplazan los servicios web SOAP con la publicación de una
arquitectura REST.
Hay dos cambios importantes:
La tecnología: se utiliza HTTP para la comunicación y JSON para el pasaje de parámetros.
La forma de armar las APIs: en lugar de usar las acciones sobre los servicios de SOAP, se empieza a utilizar la idea de GET/POST/PUT/DELETE sobre recursos publicados
¿Porqué el cambio?
- La tecnología SOAP posee mas funcionalidades, pero a costa de una complejidad muchisimo mayor, lo cual dificulta la implementación.
- En lugar de brindar servicios especificos hacia afuera, la idea es publicar recursos mas granulares e ir aumentando el nivel de cosas que se puede hacer sobre ellos. Esto permite tener una API en una arquitectura mantenible, simple y expansible.
Requisitos
- PHP 5.6+
- Extensiones:
- php5-json
- php5-curl
Seguridad
A diferencia de SOAP, en REST no se utiliza PKI (esquema de claves privadas y certificados publicos), sino que se utiliza directamente TLS (también conocido como SSL o https) para la seguridad en el transporte y protocolos estandares populares en la red (Basic Authentication, oAuth, SAML, etc.).
Para autenticación los protocolos mas sencillos de utilizar son el
de Basic Authentication y Digest que es basicamente enviar
usuario/password como un header HTTP. Esto permite autenticar
comunicaciones punto-a-punto. Para configurarlo el servidor se debe
editar el archivo
instalacion/i__{instancia}/p__{proyecto}/rest/servidor.ini
;servidor.ini
autenticacion = digest ;puede ser digest o basic
;servidor_usuarios.ini
[admin]
password = sP6lgHwQopaqepOzgIWw
En el caso del cliente, analogamente se configura el archivo
instalacion/i__{instancia}/p__{proyecto}/rest/{servicio}/cliente.ini
;cliente.ini
[conexion]
to = "http://urlservidor/baseapi"
auth_tipo = Any ;Vale tanto para Basic como para Digest.
auth_usuario = admin
auth_password = sP6lgHwQopaqepOzgIWw
A partir de la version 2.7.3, se puede incorporar un esquema de autenticación basado en certificados X509, para poder utilizar dicho esquema se deben realizar los siguientes cambios en los archivos de configuracion.
;servidor.ini
autenticacion = ssl
;servidor_usuarios.ini
[admin]
fingerprint = 8e6f46fa6ce725fcbc227ecab8466afcf1c5e35d
En el caso del cliente, analogamente se configura el archivo
instalacion/i__{instancia}/p__{proyecto}/rest/{servicio}/cliente.ini
;cliente.ini
[conexion]
to = "http://urlservidor/baseapi"
auth_tipo = "ssl"
cert_file = "/pathKeystore/certfiles/localclient.crt"
key_file = "/pathKeystore/privateKeys/localclient.key"
cert_pwd = "a78k2dfas+234dh*1" ;opcional solo si es requerido por el certificado
ca_cert = "/pathKeystore/trustedAutorities/ca.crt" ;opcional solo si la CA no esta en keystore S.O.
Por otra parte, se debe configurar Apache para que ademas de establecer las conexiones con SSL (requisito mandatorio), proporcione a php la informacion del certificado presentado por el cliente:
SSLVerifyClient require
SSLOptions +StdEnvVars +ExportCertData
Creando la API
Esta librería permite servir APIs rest de forma simple pero
estructurada. La misma no posee requisitos específicos de Toba y puede
utilizarse de manera standalone en otros sistemas. Para las versiones de
Toba 2.5 y 2.6 se encuentra ubicada en php/lib/rest. En cambio, a partir
de la versión 2.7 de Toba, la misma se encuentra dentro de la carpeta
php/vendor/siu-toba/rest, haciendo referencia a SIU-Toba/rest mediante
el esquema de composer. Leer más
Sub APIs
A partir de Toba 2.7 es posible agrupar recursos en subcarpetas dentro de /rest/, con hasta dos niveles de profundidad, permitiendo asi, definir sub APIs y lograr una mejor división semántica que facilite la aplicación de distintas configuraciones según el caso. Además estas subcarpetas sirven de prefijo de acceso en la URL, por ejemplo /personas/deportes/.
Documentación y Consola
Navegando hacia
url\_proyecto/rest(ej "http://localhost/toba_referencia/trunk/rest")
se abre la consola Swagger del proyecto. Desde ahí se puede descubrir y probar la API
rest del proyecto. La documentación se genera on-the-fly en base a los
annotations del código y el método _get_modelos() de cada clase. Para
un mayor detalle dirigirse a
Documentación de APIs REST.
Consumiendo la API
Desde toba se definen los servicios en la solapa "Datos > Servicios Web Accesibles". Se le da un identificador que luego se accede por código:
$cliente = toba::servicio_web_rest('id_del_cliente')->guzzle();
$response = $cliente->get('personas');
$personas = $response->json();
El cliente del servicio web esta implementado con la librería Guzzle
Testing
Ver Testing de Rest