https://github.com/vtex/openapi-schemas
OpenAPI 3.0 JSON schemas. Files are automatically synced to the VTEX Developer Portal.
https://github.com/vtex/openapi-schemas
openapi-schemas vtex vtex-apis
Last synced: about 1 year ago
JSON representation
OpenAPI 3.0 JSON schemas. Files are automatically synced to the VTEX Developer Portal.
- Host: GitHub
- URL: https://github.com/vtex/openapi-schemas
- Owner: vtex
- Created: 2019-12-18T17:03:16.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T20:12:02.000Z (about 2 years ago)
- Last Synced: 2024-04-14T13:20:09.851Z (about 2 years ago)
- Topics: openapi-schemas, vtex, vtex-apis
- Homepage: https://developers.vtex.com/docs/api-reference
- Size: 56.6 MB
- Stars: 103
- Watchers: 104
- Forks: 132
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# openapi-schemas
This documentation comprises VTEX's public APIs as OpenAPI 3.0 JSON schemas. Files are automatically synced with VTEX's Developer Portal [API Reference page](https://developers.vtex.com/docs/api-reference) and can be imported to Postman following [these instructions](https://learning.postman.com/docs/postman/collections/working-with-openAPI/).
## Contributing with the documentation
Please check our [Contributing Guide](CONTRIBUTING.md) for more information about how to contribute with this repository.
## Code of Conduct
Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
## API Slug Mapping
The OpenAPI schema files in this repository follow a naming convention that integrates with the Developer Portal's centralized API slug mapping system. This ensures consistent URLs and naming across documentation.
Read the [Centralized API Slug Mapping](docs/centralized-api-slug-mapping.md) documentation to learn how API names are mapped to URL slugs and how to follow the naming conventions when adding new API schemas.
## VTEX APIs
- Antifraud Provider API 
- Catalog API Seller Portal 
- Catalog API 
- Checkout API 
- Customer Credit API 
- Data Subject Rights API 
- GiftCard Hub API 
- GiftCard API 
- GiftCard Provider Protocol 
- Headless CMS API 
- Intelligent Search API 
- Intelligent Search Events API - Headless 
- Legacy CMS Portal API 
- License Manager API 
- Logistics API 
- Marketplace APIs - Sent Offers 
- Marketplace APIs - Suggestions 
- Marketplace Protocol - External Marketplace Mapper 
- Marketplace Protocol - External Marketplace Orders 
- Marketplace Protocol - External Seller Fulfillment 
- Marketplace Protocol - External Seller Marketplace 
- Master Data API - v1 
- Master Data API - v2 
- Message Center API 
- Orders API 
- Orders API - PII data architecture 
- Payment Provider Protocol 
- Payments Gateway API 
- Policies System API 
- Pricing API 
- Pricing Hub 
- Profile System API 
- Promotions & Taxes API - v2 
- Promotions & Taxes API 
- Reviews and Ratings API 
- SKU Bindings API 
- Search API 
- Session Manager API 
- Subscriptions API (v3) 
- VTEX Tracking API 
- VTEX DO API 
- VTEX ID API 
- VTEX Shipping Network API 
## Requisites
Before contributing to this repository, read the following requisites.
- The files should follow the JSON [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).
- Check our internal [OpenAPI Specification guidelines](https://www.notion.so/vtexhandbook/OpenAPI-Specification-guidelines-e3a681454798496292d6648e184a156e#344d2fc637c146ffa2ed61a119aa39ee) to make sure you meet the required file structure.
- Schema files should have a self-explanatory name that specifies the described API.
- Check [`templates/VTEX - Template openAPI.jsonc`](https://github.com/vtex/openapi-schemas/blob/master/templates/VTEX%20-%20Template%20openAPI.jsonc) to see an example of an API schema file. It shows how to represent endpoints and parameters and includes VTEX's default [`servers`](#servers) and [authorization](#authorization) information.
### Servers
OpenAPI describes the full endpoint for accessing the API as `{server URL}` + `{endpoint path}` + `{path parameters}`.
Example: an endpoint with `/api/getResults` as the path, `https://example.com` as the URL in the `server` object and no parameters will send requests to the `https://example.com/api/getResults` URL.
Example - `servers` object:
```json
"servers": [
{
"url": "https://{accountName}.{environment}.com.br",
"description": "VTEX server URL.",
"variables": {
"accountName": {
"description": "Name of the VTEX account. Used as part of the URL.",
"default": "apiexamples"
},
"environment": {
"description": "Environment to use. Used as part of the URL.",
"enum": [
"vtexcommercestable"
],
"default": "vtexcommercestable"
}
}
}
],
```
The `servers` key contains an array of objects.
### Authentication
#### Security schemes
Security schemes describe autentication types that are available in the API. You can check the all the available options in the [Security Scheme Specification](http://spec.openapis.org/oas/v3.0.0#security-scheme-object).
They should be added inside the `components` object.
The security schemes we use are:
```json
"securitySchemes": {
"appKey": {
"type": "apiKey",
"in": "header",
"name": "X-VTEX-API-AppKey",
"description": "Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
},
"appToken": {
"type": "apiKey",
"in": "header",
"name": "X-VTEX-API-AppToken",
"description": "Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys)."
},
"VtexIdclientAutCookie": {
"type": "apiKey",
"in": "header",
"name": "VtexIdclientAutCookie",
"description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours."
}
}
```
#### Security requirement
If defined inside the Open API schema, the `security` object will define the required security schemes for all endpoints. This specifies that requests should have the `X-VTEX-API-AppKey` and `X-VTEX-API-AppToken` pair or `VtexIdClientAutCookie` as part of the request header.
If defined inside an endpoint object, the `security` object will define the security scheme for that specific endpoint.
The `security` object we use at VTEX is:
```json
"security": [
{
"appKey": [],
"appToken": []
},
{
"VtexIdclientAutCookie": []
}
]
```
### Adding a new file
After creating a file for a new API reference in this repository, read [this step-by-step](https://github.com/vtexdocs/dev-portal-content#how-to-publish-a-new-api-reference-and-add-it-to-navigation) to publish it on our Developer Portal.