Practical guidelines
Working with APIs can be challenging. In the following section, you will find some guidelines to work more efficiently with APIs.
Creating products
As a vendor
When you create a product as a vendor, you do not need to specify a vendor ID; the product automatically associates with your company.
With partner role
If you're creating a product within a partner role, you'll be required to include a vendor ID to identify which company the product will be associated with.
Working with localized content
When working with localized strings keep the following things in mind:
- Supported Locales: Ensure you are using a locale that is compatible with your marketplace.
- Locale tags: Be careful with locale tags for the same language with different regional subtags, or no subtag at all. For example, differentiate between 'en' and 'en-US' or 'fr-FR' and 'fr-CA'.
- IETF BCP 47: Follow the IETF BCP 47 standard for language tags, incorporating the appropriate regional subtag (e.g., 'en-US', 'fr-FR').
Troubleshooting with userErrors
You can use (userErrors)[https://help.appdirect.com/api/graphql/usererror.doc.html] to obtain more information about issues with an API call.Unlike REST APIs, GraphQL may not include detailed user error messages in the response unless specifically requested. See the example below.
Mutaion
mutation {
createProduct(
input: {
type: WEB_APP,
addon: false,
allowMultiplePurchases: true,
usageType: MULTI_USER,
referable: false,
name: [{
locale: "fr-CA",
value: "Product Name"}]}
) {
userErrors {
... on UnspecifiedVendorError {
__typename
path
message
}
... on InvalidUsageTypeError {
__typename
message
path
type
usage
}
... on UnsupportedSupplierIdError {
__typename
message
path
}
... on URLTooLongError {
__typename
message
path
}
... on ProductSupportInvalidEmailAddressError {
__typename
message
path
}
... on ProductSupportInvalidDetailsError {
__typename
message
path
}
... on StringTooLongError {
__typename
message
path
}
... on InvalidMediaSourceError {
__typename
message
path
}
... on MissingDefaultLanguageError {
__typename
message
path
}
}
}
}
Response
{
"data": {
"createProduct": {
"userErrors": [
{
"__typename": "MissingDefaultLanguageError",
"message": "Product is missing localized value for its default language: \"en-US\"",
"path": [
"input",
"name"
]
}
]
}
}
}
Authentication scopes
When you use GraphQL APIs, you need to understand the authentication scopes required for executing specific queries and mutations. Different OAuth2 grant types support different scopes, so you need to ensure that the scope associated with your token matches the requirements for the query or mutation you intend to execute.
- API authentication: For an in-depth guide on how to authenticate, please refer to the (API Authentication documentation)[https://d1f7kt971hq16q.cloudfront.net/api/graphql/index.html].
- GraphQL schema: To find the scope requirements for specific queries and mutations, consult the (GraphQL Schema documentation)[https://d1f7kt971hq16q.cloudfront.net/api/graphql/index.html].
You can prevent unnecessary errors by verifying your token's scope alignment with the required scope for your desired query or mutation.
Was this page helpful?
Tell us more…
Help us improve our content. Responses are anonymous.
Thanks
We appreciate your feedback!