REST API has become a standard capability that customers and prospects are expecting or asking for. Why? One reason is its ease of use for both humans and computers to discover and understand the capabilities of a service using the OpenAPI Specification. (To learn more about the benefits of REST APIs, read the blog that has a link to a bootcamp recording from my colleague Ivo van de Lagemaat  https://community.rws.com/product-groups/tridion/tridion-docs/b/weblog/posts/does-tridion-docs-have-a-restful-api).

In this article, I am going to focus on a practical task: how to make the first call using our new, modern, RESTful Tridion Docs OpenAPI-based Web Services v3.

Sometimes, taking the first steps involves a learning curve; it takes time and effort. This article should help you to pass that first step easily and quickly.

Making the first request

In our example, we are using a client library, because the objects for models that are used when sending API requests and receiving responses make it easier to work with. That way, you end up focusing on the business logic of your application using the client library, and not on the maintenance of separate API calls. You could also use tools like Postman, or use HTTP files in Visual Studio 2022, but they do not allow you to use all the benefits of the OpenAPI Specification, like a language-agnostic client or object models. If you choose Postman or HTTP files, you use direct HTTP calls, with all the disadvantages that come with constructing a request message, as well as the need to maintain it.

In the example application, which you can download using the link OpenApiConsoleExample.zip, we are using the same steps as described in our public documentation regarding the client generation process. To use this example application, you need to get the clientID and clientSecret for your Tridion Docs Content Manager API Client service account. 

To do so, follow these steps or watch the animation below:

1. Navigate to your Access Management application.
2. Switch to the Service Accounts
3. Create a new Service Account. Do not reuse the default Tridion Docs Content Manager API Client that we have for Translation Organizer.
4. During creation, in the Services and roles section, you at least need to select a User role for the Tridion Docs Content Manager API.
5. Navigate to your service account, copy the clientID, and generate and copy the clientSecret.
6. Make sure that you also specify the clientID of your service account as an external ID field of the corresponding user in Tridion Docs Content Manager.

Use both values in the example application code for the serviceAccountClientId and serviceAccountClientSecret constants. Additionally, specify the base URL for your Tridion Docs deployment (in the format https://ish.example.com) in the tridionDocsUrl constant. To build and run this application, you will need .NET 8 SDK and Visual Studio Community edition or Visual Studio Code.

Now you are ready to explore Tridion Docs OpenAPI. You can try to get the list of document objects by specifying filter criteria, update one or more topics from that list, create or update a folder, or update a publication.

More code samples

As part of the Tridion Docs installation media (ISHCD), we provide various code samples that cover multiple business cases relevant to our customers.

One of these code samples represents an example use case where you have a React-based web application that communicates with Tridion Docs OpenAPI using the Backend for Frontend (BFF) layer for authorization and authentication. You can use this example as a starting point in case you need an extension that requires a frontend application that cannot be deployed as an Organize Space extension. Example code that demonstrates this code flow is on your installation media, in the \__Resources\Code\ folder, in the sample file yyyymmdd.InfoShare-Build.ReactAndOpenApiExample.zip. Alternatively, you can download it using this link 20241008.InfoShare_2D00_15.1.5808.1.ReactAndOpenApiExample.zip.

Documentation resources

Reasons to explore the Tridion Docs OpenAPI

There could be different goals of interest to explore new Tridion Docs OpenAPI.

For example, you might be a prospect who is interested in exploring the REST API capabilities of the Tridion Docs product. For such cases, you can use our public read-only swagger UI on https://developers.rws.com/tridion-docs-api-docs/api/15.1/, which reflects the Tridion Docs 15.1 state.

For another example, as a new customer of Tridion Docs with a fresh deployment, your interest could be in exploring the automation capabilities of the product. The landing page for Web Service API references gives an overview of all supported API versions. Basic concepts of using the Web Services API describe important concepts you must understand before using APIs, including Tridion Docs OpenAPI. From the modern authentication section, you can learn about how to authenticate users through different APIs. And of course, you can find out about the client generation process and code samples.

Finally, if you just upgraded to the latest and greatest Tridion Docs release, if you already have automation in place, and if you want to explore the migration process to the most recent Tridion Docs OpenAPI, Web Services API compatibility across releases will be helpful. Of course, modern authentication and the client generation process and code samples, already mentioned above, are also relevant.