Update API docs
This commit is contained in:
Michael Jackson
parent
2fc84dfe45
commit
c37101a5d2
|
|
@ -1,40 +0,0 @@
|
|||
unpkg is an [open source](https://github.com/unpkg) project built and maintained by [Michael Jackson](https://twitter.com/mjackson).
|
||||
|
||||
### Sponsors
|
||||
|
||||
The fast, global infrastructure that powers unpkg is generously donated by [Cloudflare](https://www.cloudflare.com) and [Heroku](https://www.heroku.com).
|
||||
|
||||
<div class="about-logos">
|
||||
<div class="about-logo">
|
||||
<a href="https://www.cloudflare.com"><img src="cloudflare-logo.png"></a>
|
||||
</div>
|
||||
<div class="about-logo">
|
||||
<a href="https://www.heroku.com"><img src="heroku-logo.png"></a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Cache Behavior
|
||||
|
||||
The CDN caches files based on their permanent URL, which includes the npm package version. This works because npm does not allow package authors to overwrite a package that has already been published with a different one at the same version number.
|
||||
|
||||
URLs that do not specify a package version number redirect to one that does. This is the `latest` version when no version is specified, or the `maxSatisfying` version when a [semver version](https://github.com/npm/node-semver) is given. Redirects are cached for 5 minutes.
|
||||
|
||||
Browsers are instructed (via the `Cache-Control` header) to cache assets for 4 hours.
|
||||
|
||||
### Support
|
||||
|
||||
unpkg is a free, best-effort service and cannot provide any uptime or support guarantees.
|
||||
|
||||
I do my best to keep it running, but sometimes things go wrong. Sometimes there are network or provider issues outside my control. Sometimes abusive traffic temporarily affects response times. Sometimes I break things by doing something dumb, but I try not to.
|
||||
|
||||
The goal of unpkg is to provide a hassle-free CDN for npm package authors. It's also a great resource for people creating demos and instructional material. However, if you rely on it to serve files that are crucial to your business, you should probably pay for a host with well-supported infrastructure and uptime guarantees.
|
||||
|
||||
unpkg is not affiliated with or supported by npm, Inc. in any way. Please do not contact npm for help with unpkg.
|
||||
|
||||
### Abuse
|
||||
|
||||
unpkg maintains a list of packages that are known to be malicious. If you find such a package on npm, please let us know!
|
||||
|
||||
### Feedback
|
||||
|
||||
If you think this is useful, we'd love to hear from you. Please reach out to [@unpkg](https://twitter.com/unpkg) with any questions or concerns.
|
||||
88
docs/api.md
88
docs/api.md
|
|
@ -2,12 +2,32 @@
|
|||
|
||||
Some API methods require an authentication token. This token is a [JSON web token](https://en.wikipedia.org/wiki/JSON_Web_Token) that contains a list of "scopes" (i.e. permissions).
|
||||
|
||||
Once you obtain an API token (see below) you can pass it to the server in one of two ways:
|
||||
Once you obtain an API token ([see below](#post-api-auth)) you simply include it in the `Authorization` header of your request as a base-64 encoded string, i.e.
|
||||
|
||||
* For GET/HEAD requests, use the `?token` query parameter
|
||||
* For all other requests, use the `{token}` parameter as part of the JSON in the request body
|
||||
```
|
||||
Authorization: base64(token)
|
||||
```
|
||||
|
||||
### POST /\_auth
|
||||
### GET /api/publicKey
|
||||
|
||||
The [public key](https://en.wikipedia.org/wiki/Public-key_cryptography) unpkg uses to encrypt authentication tokens, as JSON. You can also find the key as plain text [on GitHub](https://github.com/unpkg/unpkg.com/blob/master/secret_key.pub).
|
||||
|
||||
This can be useful to verify a token was issued by unpkg.
|
||||
|
||||
Required scope: none
|
||||
|
||||
Query parameters: none
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl "https://unpkg.com/api/publicKey"
|
||||
{
|
||||
"publicKey": "..."
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/auth
|
||||
|
||||
Creates and returns a new auth token. By default, auth tokens have the following scopes:
|
||||
|
||||
|
|
@ -26,50 +46,31 @@ Body parameters: none
|
|||
Example:
|
||||
|
||||
```log
|
||||
> curl -X POST "https://unpkg.com/_auth"
|
||||
> curl -X POST "https://unpkg.com/api/auth"
|
||||
{
|
||||
"token": "eyJhbGciOiJS..."
|
||||
"token": "..."
|
||||
}
|
||||
```
|
||||
|
||||
### GET /\_auth
|
||||
Please reach out to @mjackson if you need a token with additional scopes.
|
||||
|
||||
### GET /api/auth
|
||||
|
||||
Verifies and returns the payload contained in the given auth token.
|
||||
|
||||
Required scope: none
|
||||
|
||||
Query parameters:
|
||||
|
||||
* `token` - The auth token to verify and decode (required)
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl "https://unpkg.com/_auth?token=$TOKEN"
|
||||
{
|
||||
"jti": "...",
|
||||
"iss": "https://unpkg.com",
|
||||
"iat": ...,
|
||||
"scopes": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### GET /\_publicKey
|
||||
|
||||
The [public key](https://en.wikipedia.org/wiki/Public-key_cryptography) unpkg uses to encrypt authentication tokens, as JSON. You can also find the key as plain text [on GitHub](https://github.com/unpkg/unpkg/blob/master/public.key).
|
||||
|
||||
This can be useful to verify a token was issued by unpkg.
|
||||
|
||||
Required scope: none
|
||||
|
||||
Query parameters: none
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl "https://unpkg.com/_publicKey"
|
||||
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/auth"
|
||||
{
|
||||
"publicKey": "..."
|
||||
"jti": "...",
|
||||
"iss": "https://unpkg.com",
|
||||
"iat": ...,
|
||||
"scopes": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -77,26 +78,24 @@ Example:
|
|||
|
||||
To protect unpkg users and prevent abuse, unpkg manages a blacklist of npm packages that are known to contain harmful code.
|
||||
|
||||
### GET /\_blacklist
|
||||
### GET /api/blacklist
|
||||
|
||||
Returns a list of all packages that are currently blacklisted.
|
||||
|
||||
Required scope: `blacklist.read`
|
||||
|
||||
Query parameters:
|
||||
|
||||
* `token` - The auth token (required)
|
||||
Query parameters: none
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl "https://unpkg.com/_blacklist?token=$TOKEN"
|
||||
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/blacklist"
|
||||
{
|
||||
"blacklist": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /\_blacklist
|
||||
### POST /api/blacklist
|
||||
|
||||
Adds a package to the blacklist.
|
||||
|
||||
|
|
@ -104,19 +103,18 @@ Required scope: `blacklist.add`
|
|||
|
||||
Body parameters:
|
||||
|
||||
* `token` - The auth token (required)
|
||||
* `packageName` - The package to add to the blacklist (required)
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl https://unpkg.com/_blacklist -d '{"token": "$TOKEN", "packageName": "bad-package"}'
|
||||
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /\_blacklist/:packageName
|
||||
### DELETE /api/blacklist
|
||||
|
||||
Removes a package from the blacklist.
|
||||
|
||||
|
|
@ -124,12 +122,12 @@ Required scope: `blacklist.remove`
|
|||
|
||||
Body parameters:
|
||||
|
||||
* `token` - The auth token (required)
|
||||
* `packageName` - The package to remove from the blacklist (required)
|
||||
|
||||
Example:
|
||||
|
||||
```log
|
||||
> curl -X DELETE https://unpkg.com/_blacklist/bad-package -d '{"token": "$TOKEN"}'
|
||||
> curl -X DELETE -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
|
||||
{
|
||||
"ok": true
|
||||
}
|
||||
|
|
@ -137,6 +135,6 @@ Example:
|
|||
|
||||
# Stats
|
||||
|
||||
### GET /\_stats
|
||||
### GET /api/stats
|
||||
|
||||
TODO
|
||||
|
|
|
|||
Loading…
Reference in New Issue