Stricter validation coming soon in the REST API

[Updated 10-05-18]

On November 1, 2018, we will begin to validate request payloads more strictly. The change will affect all POST, PUT, PATCH, and DELETE endpoints in the REST API. Because of the strict validation changes outlined in this document, calls that currently return a 2xx success code may return a 422 Unprocessable Entity.

Please note that any documented irregularities will continue to be respected.

Before turning stricter validation on for an endpoint, we've been running an experiment using github/scientist. This alerts us to payloads that would have been invalid, allowing us to investigate why the payload would have failed. When we see a large number of errors, we've been reaching out to affected integrators and client library authors individually.

Here's what will change

While some validation in the API is already strict, lenient validation will be tightened up in the following ways:

Undocumented request body parameters will no longer be accepted. Currently, if you pass a parameter named rainbow to an endpoint that accepts only state, the API will typically ignore it. The strict validation will reject this with an error telling you that rainbow is not a valid parameter.

Strict validation only applies to parameters passed as part of the request body, and not to query parameters.

Types will be checked. Currently, if you pass the value "12" for a parameter documented as an integer, we will often coerce the value to an integer and move on. The strict validation will reject this with an error telling you that "12" is not an integer.

The same goes for other types. For example, booleans must be true or false, not the strings "true" or "false", or integers 1 or 0 or strings "1" or "0".

Enums will be case sensitive. Occasionally, we currently accept case-insensitive values where the documentation specifies a small set of exact strings. If you pass a value "GREEN" for a parameter that is documented as allowing "green" or "red", the strict validation will reject it with an error telling you that "GREEN" is not one of "green" or "red".

Optional parameters will not be nullable. You can no longer pass an optional parameter with the value null. This is perhaps the trickiest strict validation change. Currently, when the documentation specifies that the optional parameter "description" is a string, the API will typically accept "description": null. It will process this as though you did not pass the "description" parameter at all.

With the strict validation, you can either pass a valid parameter, or not pass it at all. Passing the optional string parameter "task" with a value of null will be rejected with an error that tells you that for 'properties/task', nil is not a string.

Redundant mark as read parameters will be removed.

The "mark notification(s) as read" endpoints (listed below) have long accepted an undocumented value "read" which could only ever be true. Using the following endpoints will mark notifications as read, so this redundant parameter will no longer be accepted.

• Mark notifications as read
• Mark repository notifications as read
• Mark a thread as read

If you have any questions please reach out!

Preview more complete workflows for Issues in GraphQL

We're releasing a more exhaustive Issue API in GraphQL that enables you to interact with issues in a more complete workflow like: creating issues, assigning users to an issue, or even filtering for issues already assigned.

For a more complete list of new objects and mutations made available during this preview please refer to the GraphQL docs.

To access this new API during the preview period, you must provide a custom media type in the Accept header:

  application/vnd.github.starfire-preview

Note: GraphQL APIs under preview cannot be accessed via the GraphQL Explorer at this time.

During the preview period, we may change aspects of these APIs based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

If you have any questions or feedback of other interactions you might like for issues, please let us know! We will soon be releasing a more exhaustive Pull Request API in GraphQL. Stay tuned.

Preview project card details from Issue Events API

The REST API now provides project card details in project-related issue events.

A project_card field is now included in the issue events and timeline REST API v3 responses for the following event types:

• added_to_project
• moved_columns_in_project
• removed_from_project
• converted_note_to_issue

To access this new API during the preview period, you must provide a custom media type in the Accept header:

   application/vnd.github.starfox-preview

GraphQL Preview for Resolvable Conversations

Along with the new UI for resolvable conversations, we're also releasing a GraphQL API with mutations and fields that will help people automate their workflows and create new integrations.

To access this new API during the preview period, you must provide a custom media type in the Accept header:

   application/vnd.github.catseye-preview

User-level permissions for GitHub Apps

It's now possible to add user-level permissions to your GitHub App to access certain user resources, such as user emails.

User authorization

Unlike repository and organization-level permissions, which are granted at the time of installation on an organization or user account, these permissions are granted by individual users as part of the user authorization flow.

Requesting

This new type of permission can be requested just like existing repository and organization-level permissions within your GitHub App's settings.

Existing integrations

Since these permissions are granted on an individual user basis, you can add them to your existing integration without prompting administrators to upgrade their integration. You will, however, need to send existing users through the user authorization flow to authorize the new permission and get a new user-to-server token for these requests.

Feedback

If you have any questions or feedback, please let us know!

Changes to the Checks REST API

The following changes are being introduced to the Checks REST API and will take permanent effect on August 27th, 2018.

filename is being renamed to path

Previously, constructing an annotation required you to provide a filename value. However, more accurately, this argument is a path relative to the repository's root directory. As such, the argument you need to provide is being renamed to path.

We will continue to accept the filename argument for one week, after which, path will be required. Responses will also change to provide the path value.

blob_href is no longer necessary

Previously, constructing an annotation required you to also provide a blob_href value. This argument is no longer necessary. Responses will continue to provide the blob_href value.

warning_level is being renamed to annotation_level

Previously, constructing an annotation required you to provide a warning_level value. However, this argument name is not accurate, because an annotation can also be marked as another type, such as a failure or info. As such, the argument to provide is being renamed to annotation_level.

We will continue to accept the warning_level argument for one week, after which, annotation_level will be required. Responses will also change to provide the annotation_level value.

POST /repos/:owner/:repo/check-suite-requests is being removed

This endpoint allows you to create a check suite, or rerequest every single check suite that exists on a repository.

We're removing this endpoint because, from our observations on its usage, it's not useful to be able to trigger the creation of check suites for every App on the repository.

POST /repos/:owner/:repo/check-suites/:check_suite_id/rerequest is being added

As a replacement for the above, we have provided an endpoint to only allow for the rerequesting of a single check suite. This endpoint will trigger the check_run webhook event with the action rerequested. When a check suite is rerequested, its status is reset to queued and the conclusion is cleared.

Share your feedback

During the preview period, we may change aspects of these APIs based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

If you have any questions or feedback, please let us know!

Renaming and deprecation of GitHub App Installation Access Token route

In order to Authenticate as an installation, you need to create an installation access token for your GitHub App.

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/installations/:installation_id/access_tokens

On September 4th we will be removing this route along with the GitHub Apps preview period.

You will need to update your API calls to use the following:

$ curl -i -X POST \
-H "Authorization: Bearer YOUR_JWT" \
-H "Accept: application/vnd.github.machine-man-preview+json" \
https://api.github.com/app/installations/:installation_id/access_tokens

These routes are functionally identical, so there's no need to make any further changes!

If you have any questions or feedback, please let us know!

Preview the GraphQL API for Checks Mutations

As part of our ongoing work to create a GraphQL API for Checks, you can now run mutations for creating or updating check suites and check runs!

Similar to the REST endpoints, this API is under a preview period. To access this new API during the preview period, you must provide a custom [media type][media-type] in the Accept header:

application/vnd.github.antiope-preview

Support for column information

Ever wished you could provide character-specific information using check runs? Now you can!

For both the GraphQL API and the REST API, check annotations can include a column argument to provide starting and ending column information. Check out the documentation for more information.

New webhook event for GitHub Apps using User-to-Server tokens

If your GitHub App identifies or authorizes users, those users have the option to revoke the GitHub App authorization from their settings page.

Previously, your GitHub App had no way of knowing when this occurred and may have continued to make User-to-Server requests with the now revoked access token, leading to a 401 Bad Credentials error.

Today, we're introducing the github_app_authorization webhook event, which will be delivered to your GitHub App whenever a user revokes their authorization. The event action is revoked as you can see in the example webhook payload below:

{
  "action": "revoked",
  "sender": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjIxMDMxMDY3",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

If you have any questions or feedback, please let us know!

Preview the GraphQL API for Checks

As part of our ongoing work to create a GraphQL API for Checks, you can now query for check runs, suites, and annotation information!

Similar to the REST endpoint, this API is under a preview period. To access this new API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.antiope-preview

Changes to the Checks REST API

As part of this change, we are also changing the response provided by the REST API in the CheckSuiteEvent.

Previously, when querying a check suite, the REST API would return a key named unique_check_runs_count to indicate the quantity of check runs that had run as part of the latest push. Now, this key is called latest_check_runs_count to better indicate which types of check runs are being counted.

For one week, we will make both keys available in the response; on July 18, 2018, we will remove unique_check_runs_count and only provide latest_check_runs_count.

Share your feedback

During the preview period, we may change aspects of these APIs based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.

If you have any questions or feedback, please let us know!