oryx-crm-api-request
v5.0.5
Published
Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node
Downloads
35
Readme
request.js
Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node
@octokit/request
is a request library for browsers & node that makes it easier
to interact with GitHub’s REST API and
GitHub’s GraphQL API.
It uses @octokit/endpoint
to parse
the passed options and sends the request using fetch
(node-fetch in Node).
Features
🤩 1:1 mapping of REST API endpoint documentation, e.g. Add labels to an issue becomes
request("POST /repos/:owner/:repo/issues/:number/labels", {
mediaType: {
previews: ["symmetra"]
},
owner: "octokit",
repo: "request.js",
number: 1,
labels: ["🐛 bug"]
});
👍 Sensible defaults
baseUrl
:https://api.github.com
headers.accept
:application/vnd.github.v3+json
headers.agent
:octokit-request.js/<current version> <OS information>
, e.g.octokit-request.js/1.2.3 Node.js/10.15.0 (macOS Mojave; x64)
👌 Simple to test: mock requests by passing a custom fetch method.
🧐 Simple to debug: Sets error.request
to request options causing the error (with redacted credentials).
👶 Small bundle size (<5kb minified + gzipped)
Usage
<script type="module">
import { request } from "https://cdn.pika.dev/@octokit/request";
</script>
Install with npm install @octokit/request
const { request } = require("@octokit/request");
// or: import { request } from "@octokit/request";
REST API example
// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const result = await request("GET /orgs/:org/repos", {
headers: {
authorization: "token 0000000000000000000000000000000000000001"
},
org: "octokit",
type: "private"
});
console.log(`${result.data.length} repos found.`);
GraphQL example
const result = await request("POST /graphql", {
headers: {
authorization: "token 0000000000000000000000000000000000000001"
},
query: `query ($login: String!) {
organization(login: $login) {
repositories(privacy: PRIVATE) {
totalCount
}
}
}`,
variables: {
login: "octokit"
}
});
Alternative: pass method
& url
as part of options
Alternatively, pass in a method and a url
const result = await request({
method: "GET",
url: "/orgs/:org/repos",
headers: {
authorization: "token 0000000000000000000000000000000000000001"
},
org: "octokit",
type: "private"
});
request()
request(route, options)
or request(options)
.
Options
All other options except options.request.*
will be passed depending on the method
and url
options.
- If the option key is a placeholder in the
url
, it will be used as replacement. For example, if the passed options are{url: '/orgs/:org/repos', org: 'foo'}
the returnedoptions.url
ishttps://api.github.com/orgs/foo/repos
- If the
method
isGET
orHEAD
, the option is passed as query parameter - Otherwise the parameter is passed in the request body as JSON key.
Result
request
returns a promise and resolves with 4 keys
If an error occurs, the error
instance has additional properties to help with debugging
error.status
The http response status codeerror.headers
The http response headers as an objecterror.request
The request options such asmethod
,url
anddata
request.defaults()
Override or set default options. Example:
const myrequest = require("@octokit/request").defaults({
baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
headers: {
"user-agent": "myApp/1.2.3",
authorization: `token 0000000000000000000000000000000000000001`
},
org: "my-project",
per_page: 100
});
myrequest(`GET /orgs/:org/repos`);
You can call .defaults()
again on the returned method, the defaults will cascade.
const myProjectRequest = request.defaults({
baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
headers: {
"user-agent": "myApp/1.2.3"
},
org: "my-project"
});
const myProjectRequestWithAuth = myProjectRequest.defaults({
headers: {
authorization: `token 0000000000000000000000000000000000000001`
}
});
myProjectRequest
now defaults the baseUrl
, headers['user-agent']
,
org
and headers['authorization']
on top of headers['accept']
that is set
by the global default.
request.endpoint
See https://github.com/octokit/endpoint.js. Example
const options = request.endpoint("GET /orgs/:org/repos", {
org: "my-project",
type: "private"
});
// {
// method: 'GET',
// url: 'https://api.github.com/orgs/my-project/repos?type=private',
// headers: {
// accept: 'application/vnd.github.v3+json',
// authorization: 'token 0000000000000000000000000000000000000001',
// 'user-agent': 'octokit/endpoint.js v1.2.3'
// }
// }
All of the @octokit/endpoint
API can be used:
octokitRequest.endpoint()
octokitRequest.endpoint.defaults()
octokitRequest.endpoint.merge()
octokitRequest.endpoint.parse()
Special cases
The data
parameter – set request body directly
Some 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 response = await request("POST /markdown/raw", {
data: "Hello world github/linguist#1 **cool**, and #1!",
headers: {
accept: "text/html;charset=utf-8",
"content-type": "text/plain"
}
});
// Request is sent as
//
// {
// 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!'
// }
//
// not as
//
// {
// ...
// body: '{"data": "Hello world github/linguist#1 **cool**, and #1!"}'
// }
Set parameters for both the URL/query and the request body
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
request(
"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!"
}
);