Descargo de responsabilidad
Cualquier uso de la API debe probarse en un entorno beta de Workfront antes de ejecutarse en el entorno de producción. Si algún cliente utiliza la API para un proceso que Workfront considera razonablemente intenso para el software bajo demanda (es decir, el proceso causa un efecto sustancialmente negativo en el rendimiento del software para otros clientes), Workfront se reserva el derecho de solicitar que el cliente interrumpa ese proceso. Si el cliente no cumple y el problema persiste, Workfront se reserva el derecho de finalizar el proceso.
URL de la API de Workfront
Para obtener más información acerca de la dirección URL que usará para llamar a la API de Workfront, vea Formato de dominio para llamadas a la API de Adobe Workfront.
Conceptos básicos de REST
Esta sección proporciona una introducción de alto nivel sobre cómo interactuar con la API de REST de Workfront para los siguientes principios de REST:
URI de objeto
A cada objeto del sistema se le asigna un URI único que consta del tipo de objeto y el ID. Los siguientes ejemplos muestran algunas URI que describen tres objetos únicos:
/attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
/attask/api/v15.0/task/4c78821c0000d6fa8d5e52f07a1d54d1
/attask/api/v15.0/issue/4c78821c0000d6fa8d5e52f07a1d54d2
El tipo de objeto no distingue entre mayúsculas y minúsculas y puede ser el ObjCode abreviado (como proj) o el nombre de objeto alternativo (proyecto).
Para obtener una lista de objetos, códigos de objeto válidos y campos de objeto, consulte Explorador de API.
NOTECategory y un campo personalizado es un objeto Parameter.Operaciones
Los objetos se manipulan enviando una petición HTTP a su URI único. La operación que se va a realizar se especifica mediante el método HTTP.
Los métodos HTTP estándar corresponden a las siguientes operaciones:
- GET: recupera un objeto a través del ID, busca todos los objetos mediante una consulta, ejecuta informes o ejecuta consultas con nombre
- POST: inserta un nuevo objeto
- PUT: edita un objeto existente
- DELETE: elimina un objeto
Para evitar deficiencias de cliente o límites de longitud de protocolo, se puede utilizar el parámetro de método para anular el comportamiento HTTP. Por ejemplo, se puede implementar una operación de GET publicando el siguiente URI:
GET /attask/api/v15.0/project?id=4c78...54d0&method=get
GET /attask/api/v15.0/project/4c78...54d0?method=get
Respuesta
Cada solicitud recibe una respuesta en formato JSON. La respuesta tiene un atributo de datos si la solicitud se realizó correctamente o un atributo de error si hubo un problema. Por ejemplo, la solicitud
GET /attask/api/v15.0/proj/4c7c08b20000002de5ca1ebc19edf2d5
devuelve una respuesta JSON similar a la siguiente:
{
"data": [
{
"percentComplete": 0,
"status": "CUR",
"priority": 2,
"name": "Brand New Project",
"ID": "4c7c08b20000002de5ca1ebc19edf2d5"
}
]
}
Se ha añadido seguridad especial en torno a las peticiones PUT, POST y DELETE. Cualquier solicitud que resulte de la escritura o eliminación en la base de datos solo se puede ejecutar si sessionID=abc123 está incluido en el URI. Los siguientes ejemplos muestran el aspecto que tendría esto para una petición DELETE:
GET /attask/api/v15.0/project?id=4c78...54d0&method=delete&sessionID=abc123
GET /attask/api/v15.0/project/4c78...54d0?method=delete&sessionID=abc123
Autenticación
La API autentica todas las solicitudes para garantizar que el cliente tenga acceso para ver o modificar el objeto solicitado.
La autenticación se realiza pasando un ID de sesión, el cual se puede proporcionar mediante uno de los métodos siguientes:
Autenticación del encabezado de la solicitud
El método de autenticación preferido es pasar un encabezado de solicitud denominado SessionID que contenga el token de sesión. Esto tiene la ventaja de estar protegido contra ataques de falsificación de solicitud en sitios múltiples (CSRF) y de no interferir con el URI con fines de almacenamiento en caché.
A continuación se muestra un ejemplo de encabezado de solicitud:
GET /attask/api/v15.0/project/search
SessionID: abc1234
Autenticación basada en cookies
La API utiliza la misma autenticación basada en cookies que la IU web utiliza el sistema. En el que, si un cliente inicia sesión en Workfront mediante la interfaz de usuario web, cualquier llamada AJAX realizada desde el mismo explorador utiliza la misma autenticación.
NOTEInicio de sesión
IMPORTANT/login. En lugar de ello, utilice uno de los siguientes métodos de autenticación:- Autenticación de servidor con JWT
- Autenticación de usuario con OAuth2
NOTESi utiliza un nombre de usuario y una contraseña válidos, puede utilizar la siguiente solicitud para obtener un ID de sesión:
POST /attask/api/v15.0/login?username=admin&password=user
Esto establece una cookie para autenticar solicitudes futuras, así como para devolver una respuesta JSON con el ID de sesión recién creado, el ID de usuario del usuario que ha iniciado sesión y otros atributos de sesión.
NOTEGeneración de una clave de API
Puede generar una clave de API al iniciar sesión en el sistema como ese usuario, tal como se muestra en el siguiente ejemplo:
PUT /attask/api/v15.0/user?action=generateApiKey&username= username&password=password&method=put
Recuperación de una clave de API generada anteriormente
También puede recuperar una clave de API que se haya generado anteriormente para un usuario en particular ejecutando getApiKey:
PUT /attask/api/v15.0/user?action=getApiKey&username=user@email.com&password=userspassword&method=put
Puede utilizar este resultado para autenticar cualquier llamada de API añadiendo "apiKey" como el parámetro de solicitud con este valor en lugar de un ID de sesión o un nombre de usuario y contraseña. Esto es beneficioso desde el punto de vista de la seguridad.
La siguiente solicitud es un ejemplo de recuperación de datos de un proyecto mediante apiKey:
GET /attask/api/v15.0/project/abc123xxxxx?apiKey=123abcxxxxxxxxx
Invalidar una clave de API
Si el valor de apiKey se ha visto comprometido, puede ejecutar "clearApiKey" para invalidar la clave de API actual, tal como se muestra en el siguiente ejemplo:
GET /attask/api/v15.0/user?action=clearApiKey&username=user@email.com&password=userspassword&method=put
Una vez borrada, puede volver a ejecutar getApiKey para generar una nueva clave de API.
Cerrar sesión
Cuando finaliza una sesión, puede utilizar la siguiente solicitud para cerrar la sesión del usuario, lo cual impide que se siga accediendo con el ID de sesión.
GET /attask/api/v15.0/logout?sessionID=abc1234
El ID de sesión que se va a cerrar se puede especificar como cookie, encabezado de solicitud o parámetro de solicitud.
Para cerrar la sesión de un usuario:
-
Vaya a la pantalla de inicio de sesión, pero no inicie la sesión.
-
Cambie la dirección URL a /attask/api/v15.0/project/search.
Observe que no se encuentra la página. -
Reemplace la palabra search por login?username=admin&password=user, sustituyendo su nombre de usuario y contraseña por admin y *user
*Esta sesión se almacena en el explorador como una cookie y no es necesario reiniciarla en cada petición GET posterior. -
Vuelva a cambiar la dirección URL a /attask/api/v15.0/project/search.
-
Observe la respuesta recibida.
Siempre debe incluir el ID de sesión proporcionado después del inicio de sesión al realizar peticiones PUT, POST y DELETE.
El comportamiento de GET
Utilice el método HTTP GET para recuperar uno o varios objetos y ejecutar informes.
Recuperación de objetos
Se puede mejorar la búsqueda de objetos mediante modificadores y filtros.
Recuperación de un objeto mediante el ID de objeto
Si conoce el ID de un objeto, puede recuperar el objeto accediendo a su URI único. Por ejemplo, la solicitud
GET /attask/api/v15.0/project/4c78821c0000d6fa8d5e52f07a1d54d0
devuelve una respuesta similar a la siguiente:
{
"percentComplete": 0,
"estado": "CUR",
"prioridad": 2,
"nombre": "Proyecto completamente nuevo",
"ID": "4c7c08b20000002de5ca1ebc19edf2d5"
}
Para recuperar varios objetos en la misma solicitud, especifique el parámetro de solicitud de ID y proporcione una lista de ID separados por comas, como se muestra en el siguiente ejemplo:
GET /attask/api/v15.0/project?id=4c78...54d0,4c78...54d1
Observe que la solicitud /attask/api/v15.0/project?id=… es la misma que la solicitud /attask/api/v15.0/project/....