Gathering detailed insights and metrics for @shopify/admin-api-client
Gathering detailed insights and metrics for @shopify/admin-api-client
npm install @shopify/admin-api-client
Typescript
Module System
Node Version
NPM Version
98.6
Supply Chain
100
Quality
88.3
Maintenance
100
Vulnerability
100
License
@shopify/shopify-app-remix@3.6.0
Published on 07 Jan 2025
@shopify/shopify-api@11.7.0
Published on 07 Jan 2025
@shopify/shopify-app-express@5.0.10
Published on 07 Jan 2025
@shopify/shopify-app-session-storage-sqlite@4.0.10
Published on 07 Jan 2025
@shopify/shopify-app-session-storage-redis@4.2.3
Published on 07 Jan 2025
@shopify/shopify-app-session-storage-prisma@5.2.1
Published on 07 Jan 2025
TypeScript (99.93%)
JavaScript (0.06%)
Shell (0.01%)
Total Downloads
3,109,672
Last Day
17,080
Last Week
87,437
Last Month
269,603
Last Year
3,085,637
323 Stars
5,155 Commits
126 Forks
170 Watching
62 Branches
7,090 Contributors
Minified
Minified + Gzipped
Latest Version
1.0.4
Package Id
@shopify/admin-api-client@1.0.4
Unpacked Size
126.85 kB
Size
28.98 kB
File Count
49
NPM Version
10.7.0
Node Version
18.20.4
Publised On
29 Oct 2024
Cumulative downloads
Total Downloads
Last day
12.9%
17,080
Compared to previous day
Last week
15%
87,437
Compared to previous week
Last month
-7.7%
269,603
Compared to previous month
Last year
12,738.1%
3,085,637
Compared to previous year
1
2
The Admin API Client library is for developers who want to interact with Shopify's Admin API
. The features of this library are designed to be lightweight and minimally opinionated.
npm install @shopify/admin-api-client -s
Initialize the client:
1import {createAdminApiClient} from '@shopify/admin-api-client'; 2 3const client = createAdminApiClient({ 4 storeDomain: 'your-shop-name.myshopify.com', 5 apiVersion: '2023-04', 6 accessToken: 'your-admin-api-access-token', 7});
Query for a product:
1const operation = ` 2 query ProductQuery($id: ID!) { 3 product(id: $id) { 4 id 5 title 6 handle 7 } 8 } 9`; 10 11const {data, errors, extensions} = await client.request(operation, { 12 variables: { 13 id: 'gid://shopify/Product/7608002183224', 14 }, 15});
[!NOTE] If you want to query the Admin REST API, you can use the REST client instead.
createAdminApiClient()
parametersProperty | Type | Description |
---|---|---|
storeDomain | string | The myshopify.com domain |
apiVersion | string | The requested Admin API version |
accessToken | string | The Admin API access token |
userAgentPrefix? | string | Any prefix you wish to include in the User-Agent for requests made by the library. |
retries? | number | The number of HTTP request retries if the request was abandoned or the server responded with a Too Many Requests (429) or Service Unavailable (503) response. Default value is 0 . Maximum value is 3 . |
customFetchApi? | (url: string, init?: {method?: string, headers?: HeaderInit, body?: string}) => Promise<Response> | A replacement fetch function that will be used in all client network requests. By default, the client uses window.fetch() . |
logger? | (logContent: UnsupportedApiVersionLog | HTTPResponseLog | HTTPRetryLog ) => void | A logger function that accepts log content objects. This logger will be called in certain conditions with contextual information. |
Property | Type | Description |
---|---|---|
config | AdminApiClientConfig | Configuration for the client |
getHeaders | (headers?: Record<string, string | string[]>) => Record<string, string | string[]> | Returns Admin API specific headers needed to interact with the API. If additional headers are provided, the custom headers will be included in the returned headers object. |
getApiUrl | (apiVersion?: string) => string | Returns the shop specific API url. If an API version is provided, the returned URL will include the provided version, else the URL will include the API version set at client initialization. |
fetch | (operation: string, options?: AdminAPIClientRequestOptions ) => Promise<Response> | Fetches data from Admin API using the provided GQL operation string and AdminAPIClientRequestOptions object and returns the network response. |
request | <TData>(operation: string, options?: AdminAPIClientRequestOptions ) => Promise< ClientResponse<TData> > | Requests data from Admin API using the provided GQL operation string and AdminAPIClientRequestOptions object and returns a normalized response object. |
AdminApiClientConfig
propertiesName | Type | Description |
---|---|---|
storeDomain | string | The myshopify.com domain |
apiVersion | string | The Admin API version to use in the API request |
accessToken | string | The provided public access token. If privateAccessToken was provided, publicAccessToken will not be available. |
headers | Record<string, string | string[]> | The headers generated by the client during initialization |
apiUrl | string | The API URL generated from the provided store domain and api version |
retries? | number | The number of retries the client will attempt when the API responds with a Too Many Requests (429) or Service Unavailable (503) response |
ApiClientRequestOptions
propertiesName | Type | Description |
---|---|---|
variables? | Record<string, any> | Variable values needed in the graphQL operation |
apiVersion? | string | The Admin API version to use in the API request |
headers? | Record<string, string | string[]> | Customized headers to be included in the API request |
retries? | number | Alternative number of retries for the request. Retries only occur for requests that were abandoned or if the server responds with a Too Many Request (429) or Service Unavailable (503) response. Minimum value is 0 and maximum value is 3 . |
ClientResponse<TData>
Name | Type | Description |
---|---|---|
data? | TData | any | Data returned from the Admin API. If TData was provided to the function, the return type is TData , else it returns type any . |
errors? | ResponseErrors | Error object that contains any API or network errors that occured while fetching the data from the API. It does not include any UserErrors . |
extensions? | Record<string, any> | Additional information on the GraphQL response data and context. It can include the context object that contains the localization context information used to generate the returned API response. |
ResponseErrors
Name | Type | Description |
---|---|---|
networkStatusCode? | number | HTTP response status code |
message? | string | The provided error message |
graphQLErrors? | any[] | The GraphQL API errors returned by the server |
response? | Response | The raw response object from the network fetch call |
request()
response examples1{ 2 "data": { 3 "product": { 4 "id": "gid://shopify/Product/7608002183224", 5 "title": "Aera", 6 "handle": "aera-helmet" 7 } 8 }, 9 "extensions": { 10 "cost": { 11 "requestedQueryCost": 1, 12 "actualQueryCost": 1, 13 "throttleStatus": { 14 "maximumAvailable": 1000.0, 15 "currentlyAvailable": 999, 16 "restoreRate": 50.0 17 } 18 } 19 } 20}
1{ 2 "networkStatusCode": 401, 3 "message": "Unauthorized" 4}
1{ 2 "networkStatusCode": 200, 3 "message": "An error occurred while fetching from the API. Review the `graphQLErrors` object for details.", 4 "graphQLErrors": [ 5 { 6 "message": "Field 'testField' doesn't exist on type 'Product'", 7 "locations": [ 8 { 9 "line": 17, 10 "column": 3 11 } 12 ], 13 "path": ["fragment ProductFragment", "testField"], 14 "extensions": { 15 "code": "undefinedField", 16 "typeName": "Product", 17 "fieldName": "testField" 18 } 19 } 20 ] 21}
1const productQuery = ` 2 query ProductQuery($id: ID!) { 3 product(id: $id) { 4 id 5 title 6 handle 7 } 8 } 9`; 10 11const {data, errors, extensions} = await client.request(productQuery, { 12 variables: { 13 id: 'gid://shopify/Product/7608002183224', 14 }, 15});
1const productQuery = ` 2 query ProductQuery($id: ID!) { 3 product(id: $id) { 4 id 5 title 6 handle 7 } 8 } 9`; 10 11const {data, errors, extensions} = await client.request(productQuery, { 12 variables: { 13 id: 'gid://shopify/Product/7608002183224', 14 }, 15 apiVersion: '2023-01', 16});
1const productQuery = ` 2 query ProductQuery($id: ID!) { 3 product(id: $id) { 4 id 5 title 6 handle 7 } 8 } 9`; 10 11const {data, errors, extensions} = await client.request(productQuery, { 12 variables: { 13 id: 'gid://shopify/Product/7608002183224', 14 }, 15 headers: { 16 'X-GraphQL-Cost-Include-Fields': true, 17 }, 18});
client.fetch()
to get API data1const shopQuery = ` 2 query shop { 3 shop { 4 name 5 } 6 } 7`; 8 9const response = await client.fetch(shopQuery); 10 11if (response.ok) { 12 const {errors, data, extensions} = await response.json(); 13}
1const productQuery = ` 2 query ProductQuery($handle: String) { 3 product(handle: $handle) { 4 id 5 title 6 handle 7 } 8 } 9`; 10 11const {data, errors, extensions} = await client.request(productQuery, { 12 variables: { 13 handle: 'sample-product', 14 }, 15 retries: 2, 16});
This client is compatible with the @shopify/api-codegen-preset
package.
You can use that package to create types from your operations with the Codegen CLI.
There are different ways to configure codegen with it, but the simplest way is to:
Add the preset package as a dev dependency to your project, for example:
1npm install --save-dev @shopify/api-codegen-preset
Create a .graphqlrc.ts
file in your root containing:
1import {ApiType, shopifyApiProject} from '@shopify/api-codegen-preset'; 2 3export default { 4 schema: 'https://shopify.dev/admin-graphql-direct-proxy', 5 documents: ['*.ts', '!node_modules'], 6 projects: { 7 default: shopifyApiProject({ 8 apiType: ApiType.Admin, 9 apiVersion: '2023-10', 10 outputDir: './types', 11 }), 12 }, 13};
Add "graphql-codegen": "graphql-codegen"
to your scripts
section in package.json
.
Tag your operations with #graphql
, for example:
1const {data, errors, extensions} = await client.request( 2 `#graphql 3 query Shop { 4 shop { 5 name 6 } 7 }`, 8); 9console.log(data?.shop.name);
Run npm run graphql-codegen
to parse the types from your operations.
[!NOTE] Remember to ensure that your tsconfig includes the files under
./types
!
Once the script runs, it'll create the file ./types/admin.generated.d.ts
.
When TS includes that file, it'll automatically cause the client to detect the types for each query.
UnsupportedApiVersionLog
This log content is sent to the logger whenever an unsupported API version is provided to the client.
Property | Type | Description |
---|---|---|
type | LogType['Unsupported_Api_Version'] | The type of log content. Is always set to Unsupported_Api_Version |
content | {apiVersion: string, supportedApiVersions: string[]} | Contextual info including the provided API version and the list of currently supported API versions. |
HTTPResponseLog
This log content is sent to the logger whenever a HTTP response is received by the client.
Property | Type | Description |
---|---|---|
type | LogType['HTTP-Response'] | The type of log content. Is always set to HTTP-Response |
content | { requestParams : [url, init?], response: Response} | Contextual data regarding the request and received response |
HTTPRetryLog
This log content is sent to the logger whenever the client attempts to retry HTTP requests.
Property | Type | Description |
---|---|---|
type | LogType['HTTP-Retry'] | The type of log content. Is always set to HTTP-Retry |
content | { requestParams : [url, init?], lastResponse?: Response, retryAttempt: number, maxRetries: number} | Contextual data regarding the upcoming retry attempt. requestParams : parameters used in the requestlastResponse : previous response retryAttempt : the current retry attempt count maxRetries : the maximum number of retries |
RequestParams
Property | Type | Description |
---|---|---|
url | string | Requested URL |
init? | {method?: string, headers?: HeaderInit, body?: string} | The request information |
Initialize the client:
1import {createAdminRestApiClient} from '@shopify/admin-api-client'; 2 3const client = createAdminRestApiClient({ 4 storeDomain: 'your-shop-name.myshopify.com', 5 apiVersion: '2023-04', 6 accessToken: 'your-admin-api-access-token', 7});
Query for a product:
1const response = await client.get('products/1234567890'); 2 3if (response.ok) { 4 const body = await response.json(); 5}
createAdminRestApiClient()
parametersProperty | Type | Description |
---|---|---|
storeDomain | string | The myshopify.com domain |
apiVersion | string | The requested Admin API version |
accessToken | string | The Admin API access token |
userAgentPrefix? | string | Any prefix you wish to include in the User-Agent for requests made by the library. |
retries? | number | The number of HTTP request retries if the request was abandoned or the server responded with a Too Many Requests (429) or Service Unavailable (503) response. Default value is 0 . Maximum value is 3 . |
customFetchApi? | (url: string, init?: {method?: string, headers?: HeaderInit, body?: string}) => Promise<Response> | A replacement fetch function that will be used in all client network requests. By default, the client uses window.fetch() . |
logger? | (logContent: UnsupportedApiVersionLog | HTTPResponseLog | HTTPRetryLog ) => void | A logger function that accepts log content objects. This logger will be called in certain conditions with contextual information. |
scheme? | http | https | The HTTP scheme to use for requests |
defaultRetryTime? | number | How long to wait for a retry when missing the Retry-After header |
formatPaths? | boolean | Whether to format paths, e.g. products/123 => /products/123.json |
Property | Type | Description |
---|---|---|
get | (path: string, options?: GetRequestOptions ) => Promise<Response> | Performs a GET request to the API. |
post | (path: string, options?: PostRequestOptions ) => Promise<Response> | Performs a POST request to the API. |
put | (path: string, options?: PutRequestOptions ) => Promise<Response> | Performs a PUT request to the API. |
delete | (path: string, options?: DeleteRequestOptions ) => Promise<Response> | Performs a DELETE request to the API. |
GetRequestOptions
propertiesName | Type | Description |
---|---|---|
apiVersion? | string | The Admin API version to use in the API request. |
headers? | {[key: string]: string} | Customized headers to be included in the API request. |
searchParams? | { [key: string]: string | number[] } | Any extra query string arguments to include in the request. |
retries? | number | Alternative number of retries for the request. Retries only occur for requests that were abandoned or if the server responds with a Too Many Request (429) or Service Unavailable (503) response. Minimum value is 0 and maximum value is 3. |
data? | { [key: string]: any } | string | Request body data. |
PostRequestOptions
propertiesSame options as for GET requests, but data
isn't optional.
PutRequestOptions
propertiesSame options as for POST requests.
DeleteRequestOptions
propertiesSame options as for GET requests.
1const response = await client.get('products/1234567890'); 2 3if (response.ok) { 4 const body = await response.json(); 5}
1const response = await client.put('products/1234567890', { 2 data: { 3 product: { 4 handle: 'my-new-handle', 5 }, 6 }, 7}); 8 9if (response.ok) { 10 const body = await response.json(); 11}
1const response = await client.get('products/1234567890', { 2 apiVersion: '2023-01', 3}); 4 5if (response.ok) { 6 const body = await response.json(); 7}
1const response = await client.get('products/1234567890', { 2 headers: { 3 'X-My-Custom-Header': '1', 4 }, 5}); 6 7if (response.ok) { 8 const body = await response.json(); 9}
1const response = await client.get('products/1234567890', { 2 retries: 2, 3}); 4 5if (response.ok) { 6 const body = await response.json(); 7}
No vulnerabilities found.
No security vulnerabilities found.