Package Exports
- @uploadcare/rest-client
Readme
Uploadcare REST API Client
This is an Uploadcare REST API wrapper to work with Node.js and browser.
Install
npm install @uploadcare/rest-client
Usage
Authentication
Every REST API request should be authenticated using your secret key.
According to the spec, there are two available authentication methods:
Uploadcare.Simple
Uploadcare
Uploadcare.Simple
authentication method
With the Uploadcare.Simple
authentication method, your secret key gets included in every request. This method isn't secure enough because secret key is exposed to the runtime and will be transmitted over the network.
⚠️We strongly recommend not to use this method on the client-side.⚠️
Example:
import { listOfFiles, UploadcareSimpleAuthSchema } from '@uploadcare/rest-client';
const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
publicKey: 'YOUR_PUBLIC_KEY',
secretKey: 'YOUR_SECRET_KEY',
});
const result = await listOfFiles({}, { authSchema: uploadcareSimpleAuthSchema })
Uploadcare
authentication method
With the Uploadcare
authentication method, your secret key is used to derive signature but isn't included in every request itself.
Builtin signature resolver
You can use the builtin signature resolver, which automatically generates signature in-place using crypto
module at Node.js or Web Crypto API at browsers.
import { UploadcareAuthSchema } from '@uploadcare/rest-client';
new UploadcareAuthSchema({
publicKey: 'YOUR_PUBLIC_KEY',
secretKey: 'YOUR_SECRET_KEY',
})
⚠️We strongly recommend not to use builtin signature resolver on the client-side.⚠️
Custom signature resolver
This option is useful on the client-side to avoid secret key leak. You need to implement some backend endpoint, which will generate signature. In this case, secret key will be stored on your server only and will not be disclosed.
import { UploadcareAuthSchema } from '@uploadcare/rest-client';
new UploadcareAuthSchema({
publicKey: 'YOUR_PUBLIC_KEY',
signatureResolver: async (signString) => {
/**
* You need to make HTTPS request to your backend endpoint,
* which should sign the `signString` using secret key.
*/
const signature = await yourBackendApi.getSignature(signString)
return signature
}
})
High-Level API
At the current stage, there are no any high-level wrappers here. Only low-level typed wrappers over API methods are available. It means, that there are no pagination and no conversion job status polling, just bare request wrappers.
Low-Level API
You can use low-level wrappers to call the API endpoints directly:
import { listOfFiles, UploadcareSimpleAuthSchema } from '@uploadcare/rest-client';
const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
publicKey: 'YOUR_PUBLIC_KEY',
secretKey: 'YOUR_SECRET_KEY',
});
const result = await listOfFiles({}, { authSchema: uploadcareSimpleAuthSchema })
List of all available API methods is available at the rest-client API Reference.
Settings
List of all available Settings is available at the rest-client API Reference.
Testing
npm run test:production
Security issues
If you think you ran into something in Uploadcare libraries that might have security implications, please hit us up at bugbounty@uploadcare.com or Hackerone.
We'll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.
Feedback
Issues and PRs are welcome. You can provide your feedback or drop us a support request at hello@uploadcare.com.