Skip to content

Commit 327e1e0

Browse files
author
Hubot
committed
Sync changes from upstream repository
1 parent 04b3737 commit 327e1e0

1 file changed

Lines changed: 33 additions & 3 deletions

File tree

content/guides/best-practices-for-integrators.md

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ title: Best practices for integrators | GitHub API
44

55
# Best practices for integrators
66

7+
Interested in integrating with the GitHub platform? [You're in good company](https://github.com/integrations). This guide will help you build an app that provides the best experience for your users *and* ensure that it's reliably interacting with the API.
8+
79
* TOC
810
{:toc}
911

10-
Interested in integrating with the GitHub platform? [You're in good company](https://github.com/integrations). This guide will help you design a flexible system that provides the best experience for your users and provide a secure connection for transmitted information.
11-
1212
## Secure payloads delivered from GitHub
1313

1414
It's very important that you secure [the payloads sent from GitHub](/v3/activity/events/types/). Although no personal information (like passwords) is ever transmitted in a payload, leaking *any* information is not good. Some information that might be sensitive include committer email address or the names of private repositories.
@@ -37,6 +37,36 @@ You should make use of proper HTTP status codes in order to inform users. You ca
3737

3838
## Provide as much information as possible to the user
3939

40-
Users can dig into the server responses you send back to GitHub. Ensure that your messages are clear and informative.
40+
Users can dig into the server responses you send back to GitHub. Ensure that your messages are clear and informative.
4141

4242
![Viewing a payload response](/images/payload_response_tab.png)
43+
44+
### Follow any redirects that the API sends you
45+
46+
GitHub is explicit in telling you when a resource has moved by providing a redirect status code. You should follow these redirections. Every redirect response sets the `Location` header with the new URI to go to. If you receive a redirect, it's best to update your code to follow the new URI, in case you're requesting a deprecated path that we might remove.
47+
48+
We've provided [a list of HTTP status codes](/v3/#http-redirects) to watch out for when designing your app to follow redirects.
49+
50+
### Don't manually parse URLs
51+
52+
Often, API responses contain data in the form of URLs. For example, when requesting a repository, we'll send a key called `clone_url` with a URL you can use to clone the repository.
53+
54+
For the stability of your app, you shouldn't try to parse this data or try to guess and construct the format of future URLs. Your app is liable to break if we decide to change the URL.
55+
56+
For example, when working with paginated results, it's often tempting to construct URLs that append `?page=<number>` to the end. Avoid that temptation. [Our guide on pagination](/guides/traversing-with-pagination) offers some safe tips on dependably following paginated results.
57+
58+
### Dealing with rate limits
59+
60+
The GitHub API [rate limit](/v3/#rate-limiting) ensures that the API is fast and available for everyone.
61+
62+
If you hit a rate limit, it's expected that you back off from making requests and try again later when you're permitted to do so. Failure to do so may result in the banning of your app.
63+
64+
You can always [check your rate limit status](/v3/rate_limit/) at any time. Checking your rate limit incurs no cost against your rate limit.
65+
66+
### Dealing with API errors
67+
68+
Although your code would never introduce a bug, you may find that you've encountered successive errors when trying to access the API.
69+
70+
Rather than ignore repeated `4xx` and `5xx` status codes, you should ensure that you're correctly interacting with the API. For example, if an endpoint requests a string and you're passing it a numeric value, you're going to receive a `5xx` validation error, and your call won't succeed. Similarly, attempting to access an unauthorized or nonexistent endpoint will result in a `4xx` error.
71+
72+
Intentionally ignoring repeated validation errors may result in the suspension of your app for abuse.

0 commit comments

Comments
 (0)