Say hello to our brand new Smartsheet API documentation! Today, we are very excited to announce that we are updating our API documentation and presenting a new look and feel using the industry standard, OpenAPI. The new documentation has interactive features, such as complete object modeling that can be expanded or collapsed for detail work, a “Copy” button with every code sample, and more information in line rather than forcing you to jump around to different sections.

But enough talk, let’s show you some of it!

Figure 1: Callouts for a few of the new features.

When we took on this project, we knew we wanted a tool that can address both external customer-facing capabilities and internal development velocity. It was also important to us to maintain the same high level of information in the reference section. We took this opportunity to research best practices, new tools, and new technologies and landed on OpenAPI, primarily because OpenAPI uses API definitions to auto-generate both docs and mock tests. It also allows readers like you to have an interactive and immersive experience with code samples and improved readability.

While the docs contain the same basic information: a REST endpoint and parameters using JSON format, with code samples on the right pane--the experience in using the docs is completely different. If you want to see how an object is modeled within another object, the information is in line by clicking a “>” (greater-than symbol) in the middle pane or a “+” (plus symbol) in the sample code.

In this way, every object, every parameter, and every response is modeled in JSON for you already. You can also experiment with how the payload changes when you use include or exclude query params. You no longer have to guess what a JSON object looks like.

To see the new documentation, use the following link: Smartsheet API Reference (2.0.0).

Complete Object Modeling When You Need It

Because every object is modeled, our docs allow you to compress or expand objects (default is compressed). In Figure 2, the circled image on the left contains a value with a “>” (greater-than symbol) next to it, indicating that there’s an embedded object here. With the old documentation format, you would have to follow a link to another location in the API documentation to view that object definition. With the new documentation, you can expand that object definition in line by clicking the “>” (greater-than symbol, shown here to the right of “reports”). The right image of Figure 2 shows the expanded object definition, and the arrow is now facing down (v). To compress it again, click the down-facing arrow.

Figure 2: Example of embedded object in a table.

In the same way, the code samples on the right pane are collapsed initially to give you an overview of selected language (left image in Figure 3). When you want to see more detail, click the “+” (plus sign) circled in the example. The right image of Figure 3 shows how that object is now expanded. You can click the “-” (minus sign) to re-collapse that object or you can use the “Expand All” or “Collapse All” toggles at the top of each code sample.

Figure 3: Example of embedded object in the code sample pane.

Tell Us What You Think

We plan to iterate on these new docs and continually improve them. For instance, our engineering teams can be more explicit about what a typical error code might be for each endpoint or we can build more complete SDK code samples.

Perhaps there’s still something that doesn’t quite make sense to you or you would like to see more detail about? Tell us what you think!

We love hearing from our customers and want to know what you’re building, what issues you’re struggling with, and if you have feature requests for capabilities our current API cannot yet do. Use this link for any of those types of feedback: API & Developers — Smartsheet Community

To help you transition to the new doc structure, the old docs are deprecated but still usable. Just remember that Smartsheet will no longer be updating those docs. You might want to bookmark the new doc location though!