For regular Github users, there is often a need for automation. For example, I need to periodically back up Github issues and comments to the local server. The following is a reference to Github’s API.

The documentation for the V3 API links to the official tutorial for the V3 API

Basic access paths (Root Endpoints)

When you start reading a document, curl it directly on the command line, or access InSomnia or Postman, and the 200 state is perfectly displayed. But once the link to rewrite into their own user name on the various display 404 pages. I thought it was authorization, then I tried the username and token keys in the HEADER in various ways, but it was 404. Turns out, the original is not the method of the problem, pure is the link address did not write right! In fact, just reading, without any authorization at all, allows you to directly type links to access all of anyone’s public information from the command line, Insomnia, web pages, etc. Then check the official path list Root Endpoints to get a link that seems to be accessing the wrong way. Instead, I saw a link in Stackoverflow and found various correct access paths on my own, summarized as follows:

  • In the first place! The visited link cannot have last/. Such ashttps://api.github.com/users/solomonxieI have access to my personal information, buthttps://api.github.com/users/solomonxie/Not really. The only difference is there’s an extra one/.
  • The second! Unlike normal URL access, GIthub’s API access link isCase sensitive!!!!
  • Personal information.https://api.github.com/users/ user name, the obtained data is shown as follows:

  • Personally owned REPO.https://api.github.com/users/ username/repos. You get a JSON-formatted list of repOs.
  • Repo details.https://api.github.com/repos/ username/warehouse. The path of the REPO starts to look different from the path of the personal information.
  • Gets a list of the contents of a REPO.https://api.github.com/repos/solomonxie/gists/contents, note that this only returns the contents of the root directory.
  • Gets the list of contents of the REPO neutron directory.https://api.github.com/repos/solomonxie/gists/contents/ directory name. It is important to note that the case of the original file name must be followed exactly, otherwise the information will not be available. For deeper content, write the directory name in the link column, step by step.
  • Gets information (excluding content) about a file in the REPO.https://api.github.com/repos/solomonxie/gists/contents/ file path. The file path is the full file path and case sensitive. Only basic file information is returned.
  • Gets the Raw content of a file. 1. Obtain information from the preceding filesdownload_urlThis link, you can get the original content. 2. Or directly visit:https://raw.githubusercontent.com/ username/warehouse name/branch name/file path
  • List of commits in the REPO.https://api.github.com/repos/ username/warehouse/commits.
  • A commit detail.https://api.github.com/repos/ username/warehouse name/commits a commit SHA
  • The free list.https://api.github.com/repos/ username/warehouse/issues.
  • Details of an issue.https://api.github.com/repos/ username/warehouse name/issues/serial number. Issues are numbered in the order 1,2, and 3.
  • Comments list in an issue.https://api.github.com/repos/ username/warehouse name/issues/serial number/comments.
  • Comment Details.https://api.github.com/repos/ username/warehouse name/issues/comments/comment on details of ID. The comment ID is obtained from the issues list.

Query Parameters

If you add a query criterion to the base link above, the returned data are filtered. Such as requiring only open issues to be returned, or paging list data. Commonly used as follows:

  • Paging. Format is? Page = number of pages &per_page= number of pages per page.

Such as https://api.github.com/users/solomonxie/repos?page=2&per_page=3

  • Free state. Format is? State = state.

Such as https://api.github.com/repos/solomonxie/solomonxie.github.io/issues?state=closed

Permission Authentication

First of all, you need to know that all queries up to this point do not need any permissions, give an address to return data, all public. But to create files, update, delete, and so on is to use their own account “login” to achieve. So to prepare for the following additions, deletions, and changes, take a look at permissions. Although the official website is written very simple, but if you are not familiar with the API is not immediately understood.

There are three commonly used authentication methods, Basic authentication, OAuth2 token, OAuth2 key/secret three methods have the same effect, but each has its own characteristics and convenience. Which one you choose depends on what’s convenient for you.

Authentication Method 1: Basic authentication

What do you want to do with curl?

Curl -u "Username: password" https://api.github.comCopy the code

For API debugging tools like Insomnia, simply select Basic Auth from the Auth TAB and fill in the username and password.

Authentication method 2: OAuth2 Token

About the token

This token approach, to be honest, is hard to understand without working with apis or deep understanding of REST. To put it bluntly, it is the second password. You do not need to disclose your username and password everywhere, and you can set different permissions for this “second password”, such as some can only be read and some can also be written. And this “second password” is both including the user name and password function, the whole station only this one absolutely will not repeat with others. In addition to the first time, you can also set up many tokens, namely the third, fourth, fifth… The password. It’s very convenient.

Setting token methods

Go to Github Personal Account Settings > Developer Settings > Personal Tokens. When creating a new token, you can choose the specific permission. When creating a new token, you must copy it to the local location and save it. You will only see it once, and if you forget it, you will need to regenerate it.

In addition! Note:

The token string cannot be stored in github’s repo. After testing, github automatically removes the token string once it is included in a submitted file. It took me a while to figure out that the Personal Access Token I created always disappears automatically, thinking it had a time limit.

Use the token to pass the permission authentication

There are two delivery methods, both of which are acceptable:

  1. Plaintext transmission as a parameter in the URL:
curl https://api.github.com/?access_token=OAUTH-TOKEN
Copy the code
  1. As a parameter in the header:
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
Copy the code

If the test is not done with curl but with Insomnia, it is almost the same as the basic Auth above, so it is easy to operate and will not be repeated. So far, authority authentication even if clear, but also actually validated the effective. It is strongly recommended to use Insomnia for operation with a GUI interface for easy understanding, and then switch to curl or Python after success.

Authentication method 3: OAuth2 key/secret

This is a handy alternative to the Personal Access Token: create your own OAuth app and get a pair of client_id and client_secret. As follows:

Once you have these two values, you can do authentication by explicitly adding these two parameters directly to the end of the URL connection that accesses any API, as in: https://api.github.com/users/yourusername?client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET but:

The current authentication mode does not support operations other than query. That is, only GET can obtain some API information, but cannot perform any PUT, PATCH, or DELETE operations in request.

Create a new file, Create Content

Contents The official file of the operation

  • Transmission method:PUT
  • Access path:https://api.github.com/repos/ username/warehouse name/contents/file path
  • JSON format:
{
  "message": "commit from INSOMNIA",
  "content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}
Copy the code

Fill in the JSON as shown below:

  • Note: 1. Must add permission validation (write above) 2. Data transfer format select JSON 3. The content of the file must be converted to a Base64 string and stored in a JSON variable. 4. If a folder does not exist in the file path, it will be created automatically

At first, no matter how hard I tried, I kept reporting the same error, 400 Invalid JSON, as shown below:

It turned out that there were very, very small mistakes that led to this:

The correct token processing mode is as follows: There is a space between the tokens

Authorization:token c092xxxxxx    
Copy the code

Add the message returned after the file succeeded:

Update the file Update content

The main points are as follows: 1. The transmission mode of PUT is the same as that of creating files. 2. 4. The SHA code of the file needs to be specified. 5. The contents of the file must be converted to a Base64 string and stored in a JSON variable

  • Transmission method:PUT
  • Access path:https://api.github.com/repos/ username/warehouse name/contents/file path
  • JSON format:
{
  "message": "update from INSOMNIA",
  "content": "Y3JlYXRlIGZpbGUgZnJvbSBJTlNPTU5JQQoKSXQncyB1cGRhdGVkISEhCgpJdCdzIHVwZGF0ZWQgYWdhaW4hIQ==",
  "sha": "57642f5283c98f6ffa75d65e2bf49d05042b4a6d"
}
Copy the code
  • Note: this file must be specifiedSHA codeIs equivalent to the file ID.

SHAAlthough it is the unique identification code of the file, equivalent to the ID, but it will change with the content of the file! So you have to retrieve it every time.

As for the access method, after verification, it is found that the most reliable is to use the previous get Content to obtain the information of the file, and then find SHA inside.

If the required JSON format is not entered as required, error message 422 is displayed:

Or if SHA is used incorrectly, a 409 error message appears:

If the transmission is correct, 200 will be shown to have completed the update:

Delete a file Delete content

  • Transmission method:DELETE
  • Access path:https://api.github.com/repos/ username/warehouse name/contents/file path
  • JSON format:
{
  "message": "delete a file",
  "sha": "46d2b1f2ef54669a974165d0b37979e9adba1ab2"
}
Copy the code

After the deletion is successful, 200 messages will be returned:

Add deletion issues

If you add, delete, or modify the files above, it’s pretty much the same, with different access paths and JSON formats. The only difference is that issues does not convert content to Base64 code.

Reference: Github official documentation

Add an Issue

  • Transmission method:POST
  • Access path:https://api.github.com/repos/ username/warehouse/issues
  • JSON format:
{
  "title": "Creating issue from API",
  "body": "Posting a issue from Insomnia"
}
Copy the code
  • Note: You can add label, milestone and assignees to the issue data. However, it is important to note that the milestone and Assignees must correspond exactly to the existing ranking, otherwise the creation will not complete.

Change an issue

  • Transmission method:PATCH
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/serial number
  • JSON format:
{
  "title": "Creating issue from API ---updated",
  "body": "Posting a issue from Insomnia \n\n Updated from insomnia.",
  "state": "open"
}
Copy the code
  • Note: If you add blank labels or assignees to JSON, as in"labels": []The function is to clear all tags and associated people.

Lock an issue

Don’t allow others to comment (you can)

  • Transmission method:PUT
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/serial number/lock
  • JSON format:
{
  "locked": true,
  "active_lock_reason": "too heated"
}
Copy the code
  • Note: Active_lock_reason can only have 4 values:off-topic.too heated.resolved.spamOtherwise, an error is reported.

In addition, 204 No Content is returned after a successful lock.

Unlock an issue

  • Transmission method:DELETE
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/serial number/lock
  • No JSON transmission

Add comments deletion

Refer to official documentation

Add the comment

  • Transmission method:POST
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/serial number/comments
  • JSON format:
{
  "body": "Create a comment from API"
}
Copy the code

Change the comment

  • Transmission method:PATCH
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/comments/comment ID
  • JSON format:
{
  "body": "Create a comment from API \n\n----Updated"
}
Copy the code
  • Note: in the address, the number after issues is not used, because you can pass the uniqueComment IDTraced. To view comment ids, go directly to the query link above.

Delete the comment

  • Transmission method:DELETE
  • Access path:https://api.github.com/repos/ username/warehouse name/issues/comments/comment ID
  • No transmitted data

Original address: www.cnblogs.com/chen-xing/p…