Weâ€™ve recently been working to improve CS-Cartâ€™s REST API documentation. The old documents lacked examples and explanations, so we decided to rework a few articles and ask what you think about them.
This is what weâ€™ve done so far:
- Reworked the article about orders (compare it to the old version);
- Added 3 articles about product options, option combinations, and exceptionsâ€”these entities have existed for a while, but were not documented.
Why create a new structure?
An old article was simple and brief:
- The URLs and supported methods for each URL.
- Pagination and filtering for the GET request.
- A table with the description of the fields.
A new article is based on the what the entity is, and what actions you can perform with it:
- Brief descriptionâ€”especially useful for the more complicated entities, such as exceptions.
- Getting the list of objectsâ€”pagination, filtering, and sorting are in this section, because thatâ€™s when you use them. We also added example requests and responses.
- Viewing a specific objectâ€”usually you get more data when viewing a single object. Thatâ€™s why we describe the most important fields here. We tried to make those descriptions more detailed and convenient than before.
- Creating an object.
- Updating an object.
- Deleting an object.