Skip to content

Commit 81d7375

Browse files
PriyadarshanKhadtalePriyadarshanKhadtale
authored
Merge pull request #13 from romydias21/patch-3
Revise README for improved API usage instructions
2 parents c72090b + cab7e11 commit 81d7375

File tree

1 file changed

+73
-65
lines changed

1 file changed

+73
-65
lines changed

‎README.md‎

Lines changed: 73 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,85 @@
11
<img
22
src="https://images.contentstack.io/v3/assets/blt2d43f51baca745a8/bltddc0acd6b98c881c/Contentstack-Logo" width="70" height="75">
33
<h1>Contentstack CDA/CMA OpenAPI</h1>
4-
<p>Contentstack provides OpenAPI files for its Content Delivery and Content Management REST APIs. These files are in
5-
JSON format. Using these JSON files, you can automatically generate API documentation, test API, and do a lot more.
4+
5+
<p>
6+
Contentstack provides OpenAPI files for its <a href="https://www.contentstack.com/docs/developers/apis/content-delivery-api">Content Delivery</a> and <a href="https://www.contentstack.com/docs/developers/apis/content-management-api">Content Management</a> APIs in JSON format. These files allow you to automatically generate API documentation, test requests, and streamline your development workflow.
7+
</p>
8+
<p>
9+
This tutorial walks you through how to use these JSON files with Swagger Editor to interact with Contentstack’s APIs.
610
</p>
7-
<p>This tutorial will walk you through the process of using Contentstack APIs (Content Delivery and Content Management
8-
APIs) with Swagger.</p><br>
911
<h2>Content Delivery API (CDA)</h2>
10-
<p>Version: 3.0.0 <a
11-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">[Download]</a></p>
12-
<p>Last Updated: Feb 06, 2023</p>
13-
<p><strong>Note</strong>: To use the latest version, <a
14-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">download
15-
the CDA file</a> on your system. </p>
16-
<p>To use Contentstack Content Delivery API (CDA) with Swagger, perform the following steps: </p>
12+
13+
14+
<p>
15+
To use CDA with Swagger, follow these steps:
16+
</p>
1717
<ol>
18-
<li><a
19-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">Download
20-
the CDA file</a> and go to the <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>
21-
<li>On the “Swagger Editor” page, click on <strong>File</strong>, and select the <strong>Import file</strong> option.
22-
</li>
18+
19+
<li><a href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/bltcca6e1e737dabee0/cda-openapi-3.json?v=3.0.0&disposition=download">Download the latest CDA JSON file</a> and navigate to <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>
20+
21+
<li>Click <strong>File</strong> on top-right and select <strong>Import File</strong> to upload the JSON.</li>
22+
23+
<li>Open any API request and click the <strong>Try it out</strong> button to unlock the parameter fields.</li>
24+
25+
<li>Enter your stack's values or use the default demo stack credentials.</li>
26+
27+
<li>Click <strong>Execute</strong>.</li>
2328
</ol>
24-
<p>Alternatively, if you want to use the Import URL option, you can <a
25-
href="https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/">upload the CDA
26-
file as an asset</a> in Contentstack, and then paste the asset’s URL in the prompt.</p>
27-
<ol>
28-
<li>Open any API request and click on the <strong>Try it out </strong>button. Clicking this button will unlock the
29-
fields, so you can either run the API request on our demo stack or can use your own values.</li>
30-
<li>Click on <strong>Execute</strong>.</li>
31-
</ol><br>
32-
<p>In the <strong>Responses </strong>section, you can see the following details:</p>
29+
<p>
30+
The <strong>Responses</strong> section will display the following:
31+
</p>
3332
<ul>
34-
<li>API request in CURL format</li>
35-
<li>Response body</li>
36-
<li>Status code </li>
37-
</ul><br>
38-
<h2>Content Management API</h2>
39-
<p>Version: 3.0.0 <a
40-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">[Download]</a></p>
41-
<p>Last Updated: Feb 06, 2023</p>
42-
<p><strong>Note</strong>: To use the latest version, <a
43-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">download
44-
the CMA file</a> on your system. </p>
45-
<p>To use Contentstack Content Management API (CMA) with Swagger, perform the following steps: </p>
33+
34+
<li>The API request in cURL format.</li>
35+
36+
<li>The response body (JSON).</li>
37+
38+
<li>The HTTP status code.</li>
39+
</ul>
40+
<p>
41+
<strong>Note</strong>: To ensure you are testing against the most accurate environment, always download the latest CDA file from the Contentstack documentation site.
42+
</p>
43+
<h2>Content Management API (CMA)</h2>
44+
45+
46+
<p>
47+
To use CDA with Swagger, follow these steps:
48+
</p>
4649
<ol>
47-
<li><a
48-
href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">Download
49-
the CMA file</a> and go to the <a href="https://editor.swagger.io/">Swagger Editor</a>. </li>
50-
<li>On the “Swagger Editor” page, click on<strong> File</strong>, and select the <strong>Import file </strong>option.
51-
</li>
52-
<li>Alternatively, you can <a
53-
href="https://www.contentstack.com/docs/content-managers/working-with-assets/create-upload-assets/">upload the CMA
54-
file as an asset</a> in Contentstack. Then, you can use the <strong>Import URL</strong> option and paste the
55-
asset’s URL in the prompt. </li>
56-
<li>To run any API request for CMA, make sure you have either the Management token or Auth token in hand. <ol>
57-
<li>To use a management token, refer to the Generate Management token guide. </li>
58-
<li>To use Auth token, run the <strong>Login </strong>API request, located under the <strong>User Session
59-
</strong>section. </li>
60-
</ol>
61-
</li>
62-
<li>Open any API request and click on the <strong>Try it out</strong> button. Clicking this button will unlock the
63-
fields for you to use your enter the values. </li>
64-
<li>Click <strong>Execute</strong>.</li>
65-
</ol><br>
66-
<p>In the <strong>Responses </strong>section, you can see the following details:</p>
50+
51+
<li><a href="https://assets.contentstack.io/v3/assets/blt02f7b45378b008ee/blt85399a97399b4ecf/cma-openapi-3.json?v=3.0.1&disposition=download">Download the latest CMA JSON file</a> and navigate to <a href="https://editor.swagger.io/">Swagger Editor</a>.</li>
52+
53+
<li>Click <strong>File</strong> on top-right and select <strong>Import File</strong> to upload the JSON.</li>
54+
55+
<li>Before running a request, ensure you have an authentication method ready:</li>
56+
57+
<li><strong>Management Token</strong>: We recommend using a management token for CMA requests. Refer to the <a href="https://www.contentstack.com/docs/developers/create-tokens/generate-a-management-token">Generate Management Token</a> guide for details.</li>
58+
59+
<li><strong>Authtoken</strong>: Run the <a href="https://www.contentstack.com/docs/developers/apis/content-management-api#log-in-to-your-account">Log in API request</a> under the <strong>User Session</strong> section to retrieve an <code>authtoken</code> in the response.</li>
60+
61+
<li>Open any API request and click the <strong>Try it out</strong> button to unlock the parameter fields.</li>
62+
63+
<li>Enter your stack's values or use the default demo stack credentials.</li>
64+
65+
<li>Click <strong>Execute</strong>.</li>
66+
</ol>
67+
<p>
68+
The <strong>Responses</strong> section will display the following:
69+
</p>
6770
<ul>
68-
<li>API request in CURL format</li>
69-
<li>Response body</li>
70-
<li>Status code</li>
71+
72+
<li>The API request in cURL format.</li>
73+
74+
<li>The response body (JSON).</li>
75+
76+
<li>The HTTP status code.</li>
7177
</ul>
72-
<h2>Points to note:</h2>
78+
<p>
79+
<strong>Note</strong>:
80+
</p>
7381
<ul>
74-
<li>We recommend using the Management token for executing CMA requests rather than Auth token. </li>
75-
<li>For any DELETE request that has a request body in it, you won’t be able to run it in Swagger. In such scenarios,
76-
refer to the documentation link provided in the call for more details.</li>
77-
</ul><br>
82+
83+
<li>We recommend using the Management token for executing CMA requests rather than authtoken.</li>
84+
85+
<li>For any DELETE request that has a request body in it, you won’t be able to run it in Swagger.</li></ul>

0 commit comments

Comments
 (0)