Migrar desde Rest hacia GraphQL

Diferencias en la lógica de la API

GitHub proporciona dos API: una API REST y una API GraphQL. Para más información sobre las API de GitHub, consulta "Comparación de la API REST de GitHub y la API de GraphQL".

Migrar desde Rest hacia GraphQL represente un cambio significativo en la lógica de las API. Las diferencias entre REST como un estilo y GraphQL como una especificación hacen difícil —y a menudo desaconsejable— reemplazar las llamadas a la API REST con las consultas de la API de GraphQL de una forma uno a uno. Hemos incluido ejemplos específicos de migración a continuación.

Para migrar el código de la API REST a la API de GraphQL:

• Revise la especificación de GraphQL.
• Revise el esquema de GraphQL de GitHub.
• Considera la manera en la que cualquier código existente que tengas interactúa con la API de REST de GitHub
• Use identificadores de nodo global para hacer referencia a objetos entre versiones de API.

Las ventajas significativas de GraphQL incluyen:

• Obtención de los datos que necesita y nada más
• Campos anidados
• Tipado fuerte

Aquí hay algunos ejemplos de cada una.

Ejemplo: obtener los datos que necesitas y únicamente eso

Una sola llamada de la API de REST recupera una lista de los miembros de tu organización:

curl -v http(s)://<em>HOSTNAME</em>/api/v3/orgs/:org/members

La carga útil de REST contiene datos en exceso si tu meta es recuperar únicamente los nombres y enlaces a los avatares. Sin embargo, la consulta de GraphQL recupera únicamente lo que especificas:

query {
    organization(login:"github") {
    membersWithRole(first: 100) {
      edges {
        node {
          name
          avatarUrl
        }
      }
    }
  }
}

Considera otro ejemplo: recuperar una lista de solicitudes de extracción y revisar si cada una es fusionable. Una llamada a la API REST recupera una lista de solicitudes de incorporación de cambios y sus representaciones de resumen:

curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/pulls

Para determinar si una solicitud de incorporación de cambios se puede fusionar es necesario recuperar cada solicitud individualmente de acuerdo con su representación detallada (una carga útil grande) y comprobar si su atributo mergeable es verdadero o falso:

curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/pulls/:number

Con GraphQL, solo se pueden recuperar los atributos number y mergeable para cada solicitud de incorporación de cambios:

query {
    repository(owner:"octocat", name:"Hello-World") {
    pullRequests(last: 10) {
      edges {
        node {
          number
          mergeable
        }
      }
    }
  }
}

Ejemplo: Anidar

Hacer consultas con campos anidados te permite reemplazar varios llamados de REST con menos consultas de GraphQL. Por ejemplo, para recuperar una solicitud de incorporación de cambios junto con sus confirmaciones, comentarios no revisados y revisiones mediante la API REST se necesitan cuatro llamadas independientes:

curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/pulls/:number
curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/pulls/:number/commits
curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/issues/:number/comments
curl -v http(s)://<em>HOSTNAME</em>/api/v3/repos/:owner/:repo/pulls/:number/reviews

Con la API de GraphQL, puede recuperar los datos con una sola consulta mediante campos anidados:

{
  repository(owner: "octocat", name: "Hello-World") {
    pullRequest(number: 1) {
      commits(first: 10) {
        edges {
          node {
            commit {
              oid
              message
            }
          }
        }
      }
      comments(first: 10) {
        edges {
          node {
            body
            author {
              login
            }
          }
        }
      }
      reviews(first: 10) {
        edges {
          node {
            state
          }
        }
      }
    }
  }
}

También puede ampliar la eficacia de esta consulta sustituyendo una variable por el número de solicitudes de incorporación de cambios.

Ejemplo: Escritura inflexible

Los modelos de GraphQL tienen una escritura inflexible, lo cual hace más seguro el manejo de los datos.

Imagínese, por ejemplo, que agrega un comentario a una incidencia o solicitud de incorporación de cambios con una mutación de GraphQL y, por error, especifica un entero en lugar de una cadena para el valor de clientMutationId:

mutation {
  addComment(input:{clientMutationId: 1234, subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) {
    clientMutationId
    commentEdge {
      node {
        body
        repository {
          id
          name
          nameWithOwner
        }
        issue {
          number
        }
      }
    }
  }
}

Ejecutar esta consulta recuperará errores que especificarán los tipos esperados para esta operación:

{
  "data": null,
  "errors": [
    {
      "message": "Argument 'input' on Field 'addComment' has an invalid value. Expected type 'AddCommentInput!'.",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ]
    },
    {
      "message": "Argument 'clientMutationId' on InputObject 'AddCommentInput' has an invalid value. Expected type 'String'.",
      "locations": [
        {
          "line": 3,
          "column": 20
        }
      ]
    }
  ]
}

Al entrecomillar 1234, se transforma el valor de un entero a una cadena, el tipo esperado:

mutation {
  addComment(input:{clientMutationId: "1234", subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) {
    clientMutationId
    commentEdge {
      node {
        body
        repository {
          id
          name
          nameWithOwner
        }
        issue {
          number
        }
      }
    }
  }
}