Record responses for all endpoints

[gr2m]

We want to explore how to record responses for all endpoints of GitHub’s REST API.

Here is how I would approach this. My work-in-progress lives at gr2m/github-rest-api-responses

• Use @octokit/routes to generate a list of requests that would need to be sent. Use preview headers where they are required
  (There are 508 requests for api.github.com as of March 18)
• Figure out required setups for each request. E.g. for "Add labels to issues" the setup would be
  1. Create repository
  2. Create issue
  3. Create label
     Then after the "Add labels to issues" request was recorded, delete the temporary repository again.
     We might be able to use the route path as an indication of the "hierarchy of requests", meaning what setup is needed to record a certain request.
• Once we have the list requests together with necessary setups, we have to create user accounts and other resources need to send the requests, e.g. an organization and apps.
• Run the requests, record the responses, referencing the routes recorded in @ocotkit/routes so the two can be combined easily.

The endpoint responses would differ from the current scenarios as they would all be a single request/response.

Improvements

• Record response with all preview headers enabled for the endpoint.
• Normalize responses like we do in @octokit/fixtures
• Bonus: Once responses are normalized, we could add the responses to @octokit/fixtures for testing
• Reuse setups to record requests. E.g. when recording "create an issue", that setup can be used for "get an issue" and many others.

[gr2m]

For reference, in octokit/fixtures the setup is done all manual. For example, in the project cards scenario it creates

1. A temporary repository
2. A project in that repository
3. Two columns in that project

in order to be able to record a request to move a project card (among others)

A declarative way would be much easier to maintain and collaborate on. It could look something like this

[
  {
    "scope": "repos",
    "idName": "create-in-org",
    "request": {
      "route": "POST /orgs/:org/repos",
      "org": "{ORG}",
      "repo": "tmp-{SCOPE}-{ID_NAME}-{TIMESTAMP}"
    },
    "setup": []
  },
  {
    "scope": "repos",
    "idName": "get",
    "request": {
      "route": "GET /repos/:owner/:repo",
      "owner": "{setup.repo.owner.login}",
      "repo": "{setup.repo.name}"
    },
    "setup": [
      { "scope": "repos", "idName": "create-in-org", "as": "repo"}
    ]
  },
  {
    "scope": "issues",
    "idName": "create",
    "request": {
      "route": "POST /repos/:owner/:repo/issues",
      "owner": "{setup.repo.owner.login}",
      "repo": "{setup.repo.name}",
      "title": "Issue 1"
    },
    "setup": [
      { "scope": "repos", "idName": "create-in-org", "as": "repo"}
    ]
  },
  {
    "scope": "issues",
    "idName": "get",
    "request": {
      "route": "GET /repos/:owner/:repo/issues/:number",
      "owner": "{setup.repo.owner.login}",
      "repo": "{setup.repo.name}",
      "number": "setup.issues.number"
    },
    "setup": [
      { "scope": "issues", "idName": "create", "as": "issue"}
    ]
  }
]

We would need to figure out

1. The required setup for each request
2. The request options

I’m not sure how much of this could be automated. We will definitely end up with some settings that we’d need to maintain. And I’m sure there are plenty of edge cases that will be more complex.