Introducing the GitHub API Development and Support Forum

For the past two years, we’ve run a special community forum at https://platform.github.community. This forum was designed to elicit feedback on newer API releases, specifically the GraphQL API and GitHub Apps, and it gave our ecosystem engineers direct access to your technical questions and feedback. As expected, your questions and needs have expanded as GraphQL and GitHub Apps have matured.

So today we're excited to announce that we are merging the GitHub Platform Forum into the GitHub Community Forum and expanding the focus to include all Platform features beyond the GraphQL API and GitHub Apps.

Why? We want everyone to benefit from each other's questions, workflows, and experiences with our Platform. We're confident this new forum's expanded focus and centralized location will help us and our growing community address issues quickly and efficiently. This forum is a place where you can ask technical questions about any aspect of the GitHub Platform, share your projects and ideas, and suggest new features and directions for the future.

As a contributor to the old GitHub Platform Forum, what does this mean for you? Mostly, it means learning a new URL. Your account will carry over. However, for now we will not port over existing content. We will lock the Platform Forum to read-only mode, so you can still read existing content for now but will not be able to post there.

We hope you’ll join us and all the other developers hanging out at the new GitHub API Development and Support Forum. If you have any questions, please let us know on the forum!

Improvements to the Deployment Statuses API

We are announcing a preview period with expanded functionality for the Deployments API.

Set deployment status environment

You can now update the environment of a deployment by passing the environment parameter when creating a deployment status. If an environment is not passed, the current deployment environment is used. The default environment is production.

New deployment status states

The state parameter now accepts two new states for a deployment status: in_progress and queued.

Auto-inactive status now available in production

The auto_inactive parameter allows you to automatically add a new inactive status to all prior non-transient deployments with the same repository and environment name as the created status's deployment. An inactive status is only added to deployments that have a success state. By default, auto_inactive is enabled.

Before this preview period, auto_inactive was not available in the production environment.

Preview period

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

application/vnd.github.flash-preview+json

During the preview period, we may change aspects of these API parameters 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!

Additional endpoints available for GitHub Apps

Today we are announcing the expanded availability of REST API endpoints for GitHub Apps, as we've enabled another batch of endpoints. For a complete list of endpoints enabled for GitHub Apps, see "Available endpoints".

Recently enabled server-to-server and user-to-server endpoints are available in these APIs:

Additional recently enabled user-to-server endpoints are available in these APIs:

How can I try it?

To access this functionality, you’ll need to provide the following custom media type in the Accept header:

application/vnd.github.machine-man-preview+json

What about other endpoints?

For now, this will be the last set of endpoints we enable for the REST API. If you have specific requests or feedback, come chat with us in the Platform forum.

Denying new GitHub Services

As we announced back in April, starting today, additional GitHub Services cannot be added to any repository on GitHub.com, via the UI or API. You can continue to edit or delete existing GitHub Services. For more information, see "Replacing GitHub Services."

Ensure that your repositories use newer APIs available for handling events according to the following changes that will take place:

  • Currently, the "Create a hook" endpoint accepts a required argument called name, which can be set to web for webhooks, or the name of any valid service. Starting today, this endpoint does not require name to be provided; if it is, it will only accept web as a valid value.

  • For the week of November 5th, 2018, there will be a week-long brownout for GitHub Services. Any GitHub Service installed on a repository will not receive any payloads. Normal GitHub Services operations will resume at the conclusion of the brownout.

  • On January 31, 2019, we will permanently stop delivering all installed services' events on GitHub.com.

Please contact us if you have any questions!

Pass header to test strict validation in REST API

As previously announced, we will begin to validate request payloads more strictly in the REST API starting on November 1, 2018.

If you wish to test the strict validation before November 1, you can pass the following header:

application/vnd.github.speedy-preview+json

If you have any questions, please reach out!

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.

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

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

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.

Note: This update only affects users of GitHub.com and future versions of GitHub Enterprise.

Feedback

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

Recent Posts

Subscribe to the RSS feed