Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
@octokit/endpoint
Advanced tools
The @octokit/endpoint npm package is designed to convert GitHub API endpoint options into the URL and headers format that the GitHub REST API expects. It's part of the Octokit suite of libraries which are used to interact with the GitHub API in a more convenient and structured way. This package is particularly useful for developers who need to make custom requests to the GitHub API beyond what higher-level Octokit libraries provide, allowing for detailed control over the request parameters and headers.
Creating a custom GitHub REST API endpoint
This code sample demonstrates how to create a custom endpoint for fetching issues from a GitHub repository. You specify the HTTP method, the URL pattern, and any necessary headers. The `owner` and `repo` parameters are used to fill in the URL pattern.
{
"method": "GET",
"url": "/repos/{owner}/{repo}/issues",
"headers": {
"accept": "application/vnd.github.v3+json"
},
"owner": "octokit",
"repo": "endpoint.js"
}
Converting endpoint options to request URL and headers
This example shows how to use the @octokit/endpoint package to convert endpoint options into a format that can be used to make an HTTP request. It includes the method, URL, headers, and other parameters like `title` for the body of the request.
const { endpoint } = require('@octokit/endpoint');
const options = endpoint({
method: 'POST',
url: '/repos/{owner}/{repo}/issues',
headers: {
accept: 'application/vnd.github.v3+json'
},
owner: 'octokit',
repo: 'endpoint.js',
title: 'New issue title'
});
console.log(options); // Logs the URL and headers object ready for the request
node-fetch is a lightweight module that brings window.fetch to Node.js. While it doesn't directly offer GitHub API endpoint conversion like @octokit/endpoint, it's commonly used for making HTTP requests to APIs, including GitHub's REST API. Developers can manually construct their requests to GitHub or any other service.
Axios is a promise-based HTTP client for the browser and Node.js. Similar to node-fetch, it allows for making HTTP requests to REST APIs, including GitHub's. It provides more features out of the box compared to node-fetch, such as automatic JSON data transformation and request and response interception. However, like node-fetch, it requires manual setup for calling GitHub API endpoints.
Turns REST API endpoints into generic request options
@octokit/endpoint
combines GitHub REST API
with your options and turns them into generic request options which you can
then pass into your request library of choice.
const endpoint = require('@octokit/endpoint')
// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const options = endpoint('GET /orgs/:org/repos', {
headers: {
authorization: 'token 0000000000000000000000000000000000000001'
},
org: 'octokit',
type: 'private'
})
Alternatively, pass in a method and a url
const options = endpoint({
// route options
method: 'GET',
url: '/orgs/:org/repos',
headers: {
authorization: 'token 0000000000000000000000000000000000000001'
},
// parameters
org: 'octokit',
type: 'private'
})
The method returns an object with 3 or 4 keys
key | type | description |
---|---|---|
method | String | The http method. Always lowercase |
url | String | The url with placeholders replaced with passed parameters |
headers | Object | All header names are lowercased |
body | Any | The request body if one is present. Only for PATCH , POST , PUT , DELETE requests |
The above examples shown above return
{
method: 'get',
url: 'https://api.github.com/orgs/octokit/repos?type=private',
headers: {
accept: 'application/vnd.github.v3+json',
authorization: 'token 0000000000000000000000000000000000000001',
'user-agent': 'octokit/endpoint.js v1.2.3'
}
}
@octokit/endpoint
with common request libraries// using with fetch (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
fetch(options.url, ...options)
// using with request (https://github.com/request/request)
request(options)
// using with got (https://github.com/sindresorhus/got)
got[options.method](options.url, options)
// using with axios
axios(options)
name | type | description |
---|---|---|
baseUrl
| String |
Required. Any supported http verb, case insensitive. Defaults to https://api.github.com .
|
headers
| Object |
Custom headers. Passed headers are merged with defaults:headers['user-agent'] defaults to octokit-endpoint.js/1.2.3 (where 1.2.3 is the released version).headers['accept'] defaults to application/vnd.github.v3+json . |
method
| String |
Required. Any supported http verb, case insensitive. Defaults to Get .
|
url
| String |
Required. A path or full URL which may contain :variable or {variable} placeholders,
e.g. /orgs/:org/repos . The url is parsed using url-template.
|
All other options will passed depending on the method
and url
options.
url
, it will be used as replacement. For example, if the passed options are {url: '/orgs/:org/repos', org: 'foo'}
the returned options.url
is https://api.github.com/orgs/foo/repos
method
is GET
or HEAD
, the option is passed as query parameterOverride or set default options. Example:
const request = require('request')
const myEndpoint = require('@octokit/endpoint').defaults({
baseUrl: 'http://github-enterprise.acme-inc.com/api/v3',
headers: {
'user-agent': 'myApp/1.2.3',
authorization: `token 0000000000000000000000000000000000000001`
},
org: 'my-project',
per_page: 100
})
request(myEndpoint(`GET /orgs/:org/repos`))
You can call .defaults()
again on the returned method, the defaults will cascade.
const myProjectEndpoint = endpoint.defaults({
baseUrl: 'http://github-enterprise.acme-inc.com/api/v3',
headers: {
'user-agent': 'myApp/1.2.3'
},
org: 'my-project'
})
const myProjectEndpointWithAuth = myProjectEndpoint.defaults({
headers: {
authorization: `token 0000000000000000000000000000000000000001`
}
})
myProjectEndpointWithAuth
now defaults the baseUrl
, headers['user-agent']
,
org
and headers['authorization']
on top of headers['accept']
that is set
by the global default.
data
parameter – set request body directlySome endpoints such as Render a Markdown document in raw mode don’t have parameters that are sent as request body keys, instead the request body needs to be set directly. In these cases, set the data
parameter.
const options = endpoint('POST /markdown/raw', {
data: 'Hello world github/linguist#1 **cool**, and #1!',
headers: {
accept: 'text/html;charset=utf-8',
'content-type': 'text/plain'
}
})
// options is
// {
// method: 'post',
// url: 'https://api.github.com/markdown/raw',
// headers: {
// accept: 'text/html;charset=utf-8',
// 'content-type': 'text/plain',
// 'user-agent': userAgent
// },
// body: 'Hello world github/linguist#1 **cool**, and #1!'
// }
There are API endpoints that accept both query parameters as well as a body. In that case you need to add the query parameters as templates to options.url
, as defined in the RFC 6570 URI Template specification.
Example
endpoint('POST https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}', {
name: 'example.zip',
label: 'short description',
headers: {
'content-type': 'text/plain',
'content-length': 14,
authorization: `token 0000000000000000000000000000000000000001`
},
data: 'Hello, world!'
})
FAQs
Turns REST API endpoints into generic request options
The npm package @octokit/endpoint receives a total of 6,268,158 weekly downloads. As such, @octokit/endpoint popularity was classified as popular.
We found that @octokit/endpoint demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.