Introducción a las API REST

  • Artículo

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Integre la aplicación con Azure DevOps mediante las API REST proporcionadas en este artículo.

Las API siguen un patrón común, como en el ejemplo siguiente.

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Sugerencia

A medida que evolucionan las API, se recomienda incluir una versión de API en cada solicitud. Esta práctica puede ayudarle a evitar cambios inesperados en la API que podrían interrumpirse.

Azure DevOps Services

Para Azure DevOps Services, instance es dev.azure.com/{organization} y collection es DefaultCollection, por lo que el patrón es similar al ejemplo siguiente.

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

En el ejemplo siguiente se muestra cómo obtener una lista de proyectos de una organización.

curl -u {username}:{personalaccesstoken} https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

Si desea proporcionar el token de acceso personal (PAT) a través de un encabezado HTTP, primero debe convertirlo en una cadena Base64. En el ejemplo siguiente se muestra cómo convertir a Base64 mediante C#. A continuación, se puede proporcionar la cadena resultante como un encabezado HTTP en el formato .

Authorization: Basic BASE64PATSTRING

En el ejemplo siguiente se muestra C# mediante la clase HttpClient.

public static async void GetProjects()
{
	try
	{
		var personalaccesstoken = "PAT_FROM_WEBSITE";

		using (HttpClient client = new HttpClient())
		{
			client.DefaultRequestHeaders.Accept.Add(
				new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

			client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
				Convert.ToBase64String(
					System.Text.ASCIIEncoding.ASCII.GetBytes(
						string.Format("{0}:{1}", "", personalaccesstoken))));

			using (HttpResponseMessage response = client.GetAsync(
						"https://dev.azure.com/{organization}/_apis/projects").Result)
			{
				response.EnsureSuccessStatusCode();
				string responseBody = await response.Content.ReadAsStringAsync();
				Console.WriteLine(responseBody);
			}
		}
	}
	catch (Exception ex)
	{
		Console.WriteLine(ex.ToString());
	}
}

La mayoría de nuestros ejemplos usan PAT, ya que son un ejemplo compacto para autenticarse con el servicio. Sin embargo, hay varios mecanismos de autenticación disponibles para Azure DevOps Services, incluida la biblioteca de autenticación de Microsoft (MSAL), OAuth y tokens de sesión. Para obtener más información, consulte Guía de autenticación para ayudarle a determinar cuál es el más adecuado para su escenario.

Azure DevOps Server

Para Azure DevOps Server, instance es {server:port}. El puerto predeterminado para una conexión que no es SSL es 8080.

La colección predeterminada es DefaultCollection, pero puede usar cualquier colección.

Aquí se muestra cómo obtener una lista de proyectos de Azure DevOps Server mediante el puerto y la colección predeterminados en SSL:

curl -u {username}:{personalaccesstoken} https://{server}/DefaultCollection/_apis/projects?api-version=2.0

Para obtener la misma lista en una conexión no SSL:

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

En estos ejemplos se usan PAT, que requieren que cree un PAT.

Respuestas

Debería obtener una respuesta como esta.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

La respuesta es JSON, que suele ser lo que se obtiene de las API REST, aunque hay algunas excepciones, como los blobs de Git.

Ahora, puede buscar en torno a las áreas de API específicas, como el seguimiento de elementos de trabajo o Git, y acceder a los recursos que necesita. Siga leyendo para obtener más información sobre los patrones generales que se usan en estas API.

Verbos HTTP

Verbo Se usa para...
GET Obtener un recurso o una lista de recursos
PUBLICAR Creación de un recurso, Obtención de una lista de recursos mediante una consulta más avanzada
PUT Cree un recurso si no existe o, si lo hace, actualícelo.
PATCH Actualización de un recurso
Delete Eliminar un recurso

Encabezados de solicitud y contenido de la solicitud

Al proporcionar el cuerpo de la solicitud (normalmente con los verbos POST, PUT y PATCH), incluya encabezados de solicitud que describen el cuerpo. Por ejemplo,

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

Invalidación del método HTTP

Algunos servidores proxy web solo pueden admitir los verbos HTTP GET y POST, pero no verbos HTTP más modernos como PATCH y DELETE. Si las llamadas pueden pasar a través de uno de estos servidores proxy, puede enviar el verbo real mediante un método POST, con un encabezado para invalidar el método. Por ejemplo, es posible que quiera actualizar un elemento de trabajo (PATCH _apis/wit/workitems/3), pero es posible que tenga que pasar por un proxy que solo permita GET o POST. Puede pasar el verbo adecuado (PATCH en este caso) como parámetro de encabezado de solicitud HTTP y usar POST como método HTTP real.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Códigos de respuesta

Respuesta Notas
200 El éxito y hay un cuerpo de respuesta.
201 Correcto, al crear recursos. Algunas API devuelven 200 al crear correctamente un recurso. Consulte los documentos de la API que usa para asegurarse.
204 El éxito y no hay ningún cuerpo de respuesta. Por ejemplo, obtendrá esta respuesta al eliminar un recurso.
400 Los parámetros de la dirección URL o del cuerpo de la solicitud no son válidos.
401 Error de autenticación. A menudo, esta respuesta se debe a un encabezado de autorización que falta o tiene un formato incorrecto.
403 El usuario autenticado no tiene permiso para realizar la operación.
404 El recurso no existe o el usuario autenticado no tiene permiso para ver que existe.
409 Hay un conflicto entre la solicitud y el estado de los datos en el servidor. Por ejemplo, si intenta enviar una solicitud de incorporación de cambios y ya hay una solicitud de incorporación de cambios para las confirmaciones, el código de respuesta es 409.

Uso compartido de recursos entre orígenes (CORS)

Azure DevOps Services admite CORS, lo que permite que el código JavaScript servido desde un dominio distinto de dev.azure.com/* realizar solicitudes de Ajax a las API REST de Azure DevOps Services. Cada solicitud debe proporcionar credenciales (las PAT y los tokens de acceso de OAuth son ambas opciones compatibles). Ejemplo:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

(reemplace por myPatToken un token de acceso personal)

Control de versiones

Las API REST de Azure DevOps tienen versiones para asegurarse de que las aplicaciones y los servicios siguen funcionando a medida que evolucionan las API.

Directrices

  • Especifique la versión de la API con cada solicitud (necesaria).
  • Dar formato a las versiones de API como se indica a continuación: {major}. {minor}-{stage}. {resource-version}. Por ejemplo, 1.0, 1.1, 1.2-preview, 2.0.
  • Especifique una revisión determinada de la API cuando se encuentra en versión preliminar mediante el siguiente formato de versión: 1.0-preview.1, 1.0-preview.2. Una vez publicada una API (1.0, por ejemplo), su versión preliminar (1.0-preview) está en desuso y se puede desactivar después de 12 semanas.
  • Actualice a la versión publicada de la API. Una vez desactivada una API en versión preliminar, se rechazan las solicitudes que especifican -preview la versión.

Uso

Especifique la versión de la API en el encabezado de la solicitud HTTP o como parámetro de consulta de dirección URL.

Encabezado de solicitud HTTP:

Accept: application/json;api-version=1.0

Parámetro de consulta:

GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0

Versiones compatibles

Para obtener información sobre las versiones admitidas, consulte Versiones admitidas de la API rest.