Feedback Wanted: Rest Api Documentation


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:

Please take a look and tell us what you think in this topic. Is the article structure convenient for you? Is there enough information? Are the examples convenient and understandable, or would you prefer cURL examples, like here? We are looking forward to your feedback.

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.
There were no examples of how to do something with the API.

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.
The last three sections describe what was only implied in the old articles. Now there are request and JSON examples. That way the reader has to deduce less.