Learn how to make an API request
You can use the TEST METHOD
button in VTEX API reference to test API requests as you read the documentaion. In this tutorial you will learn how to use this feature.
Before you begin
Requests to VTEX APIs usually require authentication, either with application keys or user tokens. The Developer Portal TEST METHOD
requires application keys, meaning a pair of appKey
and appToken
.
Make sure you have a valid pair of appKey
and appToken
associated with roles with the necessary permissions to execute a request. If you do not have this credential yet, learn more about how to create application keys at the Application keys guide.
Testing a request on Developer Portal
The example below is based on the List orders endpoint, but these instructions apply for any endpoint you wish to try. Feel free to follow along.
To try out an API request directly on Developer Portal, follow these steps:
- Head to the API reference page of the endpoint you wish to test, such as the List orders endpoint.
- Read the documentation and fill in necessary parameters of your request, such as headers, query parameters, and request body fields.
- Scroll to the Authentication section. It may be on the top of the page at the right side of your screen, or on the bottom, depending on your window size.
- Fill in your appKey in the
X-VTEX-API-AppKey
field. - Fill in your appToken in the
X-VTEX-API-AppToken
field. - Hover your mouse cursor over the
Base URL
field to see theaccountName
andenvironment
. - Fill in the
accountName
field with your VTEX account name. - Fill in the
environment
. If you do not know which environment to use, tryvtexcommercestable
. - Click the
TEST METHOD
button. This will send your request to the desired API endpoint. - Check your response below the request.
If you receive a 200 OK
, a 201 Created
or a 204 No Content
response, it means you sucessfully made a request to a VTEX API.
If you get a
401 - Unauthorized
as response, review the application key and token and try again. Make sure that the right permissions are defined in the roles associated with the application key and that you copied the exact key and token values into the headers of the request.
Using an API testing platform
You can export API specification or example requests to be used with Postman or the API platform of your choice.
Request examples
As you fill in request parameters in VTEX API reference, as described above in steps 4 to 8, the request box is automattically updated. You can find this box below the Base URL
field described above.
This means you can copy this content to be imported into other software.
Downloading API specifications
Our API reference documentation is built using the OpenAPI 3.0 (OAS 3.0) standard.
It is possible to download the OAS 3.0 schemas in three ways, via GitHub, the API SPEC button or the POSTMAN button.
GitHub
To download the schemas from GitHub, follow the steps below:
- Access the repository OpenAPI Schemas.
- Click the <>Code button.
- Click Download ZIP.
In a short time, the file with all the repository's schemas will be available on your computer.
API SPEC
In each Developer Portal API Reference you will find two buttons referring to the SPEC API at the top of the page: DOWNLOAD OPENAPI SPEC and VIEW OPENAPI SPEC.
The DOWNLOAD OPENAPI SPEC button is used to download the collection schema file in JSON format to the computer, the VIEW OPENAPI SPEC button is used to view the collection schema in the browser.
Postman
In each Developer Portal API Reference you will also find two buttons referring to Postman at the top of the page: DOWNLOAD POSTMAN COLLECTION and VIEW POSTMAN COLLECTION.
The DOWNLOAD POSTMAN COLLECTION button is used to download the collection schema file in JSON format. This file can be imported into POSTMAN for testing. The VIEW POSTMAN COLLECTION button is used to view the collection schema in your browser.
Another option for importing a schema into Postman is to copy the cURL
from the desired API Reference and follow the tutorial Import cURL commands.