Conceptos básicos de API de servicio Web de Service Desk

• Consultar datos en su organización.
• Agregar, actualizar y suprimir datos.

Este artículo proporciona información sobre los conceptos básicos de API de servicio web y contiene los siguientes temas:

Características de llamadas de API

Las llamadas de API contienen las siguientes características:

• Solicitudes y respuestas: la aplicación de cliente prepara y envía una solicitud al servicio Web del Centro de servicio al usuario mediante la API, el servicio Web del Centro de servicio al usuario procesa la solicitud y devuelve una respuesta y, por último, la aplicación de cliente se encarga de la respuesta.
• Sincrónicas: una vez que la llamada de API se invoca, su aplicación de cliente espera hasta que recibe una respuesta del servicio. Las llamadas asincrónicas no son compatibles.
• Confirmación automática frente a la reversión por error: de forma predeterminada, todas las operaciones que escriben a un objeto del Centro de servicio al usuario, se confirman automáticamente. Esto es análogo a la configuración de AUTOCOMMIT en SQL.
• Para las llamadas create(), update() y delete() que intentan escribir en varios registros para un objeto, la operación de escritura para cada registro se trata como una transacción separada. Por ejemplo, si una aplicación de cliente intenta crear dos nuevas cuentas, éstas se crean mediante operaciones de inserción mutuamente exclusivas que se realizan correctamente o producen un fallo individualmente, no como grupo.  

• La organización deberá estar habilitada para acceder a la API del servicio Web, y el usuario que intenta acceder a la API de servicio Web deberá tener una licencia del tipo "Servicio Web".
• Si sus permisos configurados permiten acceso a los datos. Su aplicación de cliente inicia sesión como usuario en el servicio Web del Centro de servicio al usuario. El perfil asociado al usuario registrado concede o denega acceso a los objetos y los campos específicos en la organización.
• Cuando una aplicación inicia sesión en la API, todas las transacciones se ejecutan como el usuario que se conecta. Por lo tanto, para proteger la seguridad de los datos, proporcione a dicho usuario (el usuario que ha iniciado sesión) solamente los permisos necesarios para ejecutar correctamente todas las llamadas realizadas por la aplicación.
• Si un cambio particular comprometiese la integridad referencial de los datos del Centro de servicio al usuario de su organización.
• Si un campo determinado en un objeto se puede actualizar o no. Por ejemplo, no se pueden cambiar campos de sólo lectura en llamadas create() o update().
• La API aplica automáticamente a las reglas para los objetos personalizados. Por ejemplo, este comportamiento afecta a los campos configurados como exclusivos o necesarios en la interfaz del centro de servicio al usuario.

Tipos de formato de datos de salida del servicio web

ServiceAide Cloud Service Management es compatible con los siguientes tipos de datos estándar del protocolo HTTP:

• JSON - http://json.org/
• XML - http://en.wikipedia.org/wiki/XML
• JAVA BEAN - http://en.wikipedia.org/wiki/JavaBean

Seguridad

Las aplicaciones de cliente que acceden a los datos del Centro de servicio al usuario para la organización están sujetas a las mismas protecciones de seguridad que se utilizan en la interfaz de usuario del Centro de servicio al usuario. Las aplicaciones de cliente deben iniciar sesión con las credenciales válidas de una organización. El servidor autentica estas credenciales y, si son válidas, permite el acceso a la operación de servicio Web.

El administrador del Centro de servicio al usuario de una organización controla la disponibilidad de diversas funciones y vistas configurando perfiles y asignando usuarios a estas funciones y vistas. Para acceder a la API (para emitir llamadas y recibir los resultados de la llamada), se deberá conceder a los usuarios la licencia Servicios web. Las aplicaciones de cliente solo pueden consultar o actualizar los objetos y los campos a los que su segmento de cliente tiene acceso utilizando el perfil del usuario que ha iniciado la sesión.

Para acceder mediante la API o un cliente, el usuario debe utilizar su token de seguridad o proporcionar su ID de inicio de sesión y contraseña para iniciar sesión. Un token de seguridad es una clave generada automáticamente desde el Centro de servicio al usuario.

Control de errores

Las llamadas de API devuelven datos de error que su aplicación de cliente puede utilizar para identificar y resolver errores de tiempo de ejecución. Si un error se produce durante la invocación de la mayor parte de las llamadas de API, la API proporcionará los siguientes tipos de tratamiento de errores:

• Para errores que se originan por mensajes mal formados, autenticación errónea o problemas similares, la API devuelve una respuesta de servicio predeterminada con el código de estado apropiado y un mensaje de estado descriptivo.
• Para la mayoría de las llamadas, si el error ocurre a causa de un problema específico de la consulta, la API devuelve un error. Por ejemplo, si una solicitud create() contiene valores que se deben actualizar para campos de solo lectura.

Entidades compatibles

Se puede utilizar la API del servicio web de ServiceAide Cloud Service Management para acceder y cambiar los siguientes tipos de entidad:

• Archivo adjunto
• Petición de cambio
• Elemento de configuración
• Comunicación
• Contacto
• Búsqueda definida
• Incidente
• Artículo de conocimiento
• Organización
• Problema
• Proyectos
• Solicitud de servicio
• Grupo de soporte
• Ticket de tarea
• Ticket
• Lista de valores
• Registro de trabajo

La lista de entidades compatibles puede cambiar en el futuro. Es posible que algunas de las entidades no sean accesibles para un usuario concreto, dependiendo de los permisos del usuario y de la organización.

Operaciones admitidas

Las llamadas de API representan operaciones específicas que sus aplicaciones de cliente pueden invocar en el tiempo de ejecución para realizar tareas. Los servicios web de Cloud Service Management son compatibles con los siguientes tipos de operaciones:

Formulario general de la API del servicio web de ServiceAide Cloud Service Management Web

Una solicitud de un cliente inicia cada llamada de API y tiene una respuesta desde el servidor. Las llamadas de API nunca se inician del servidor al cliente. Cada llamada de API tiene un nombre de método, que es una de las operaciones descritas en la sección Operaciones admitidas.

La API de servicios Web de ServiceAide Cloud Service Management permite codificar llamadas mediante SOAP (protocolo de acceso a objetos simples) o mediante XML-RPC, un mecanismo de RPC sencillo codificado en XML.

Implementación de SOAP

La API del servicio web de ServiceAide Cloud Service Management le permite codificar las llamadas mediante SOAP. SOAP (Protocolo de acceso a objetos simples) es un protocolo basado en XML para intercambiar información. Consulte http://www.w3.org/TR/SOAP/ para obtener una descripción detallada de SOAP.

Todas las operaciones compatibles están disponibles en la implementación de SOAP. Consulte la sección Operaciones admitidas.

Cada llamada de SOAP se deberá hacer a un nombre de host de servidor de aplicaciones del Centro de servicio al usuario con un nombre de servlet de webservices/xxxx. Esta sección describe la especificación de SOAP de alto nivel para la API del Centro de servicio al usuario.

Consulte el WSDL de Service Desk en http://www.w3.org/TR/SOAP/ para obtener una especificación más técnica.

Espacios de nombres de SOAP

SOAP utiliza espacios de nombres distintos para los diferentes elementos y atributos. El espacio de nombre depende del rol que los datos desempeñan en el formato, el tratamiento o la codificación de mensajes. Los espacios de nombres reflejan cómo todas las definiciones de los tipos de datos en SOAP se delegan al esquema XML.

La API de servicio web de Cloud Service Management utiliza los siguientes espacios de nombres.