Getting Started
> The getting started guide is designed to help a developer go from being a newbie with your API to comfortably performing a basic task. Refer to the "Quick Start Section" of the API style guide for more details on documenting a getting started guide (formally referred to as a "Quick Start Guide").
> Provide an introduction of what the quick start guide will help them achieve.
The following sections introduce you to the XYZ API resources and provide instructions to make your first API request. Learn how to setup an account, obtain an API token, and retrieve the resources. Examples will be shown using the command line with cURL and using Python code.
> Provide the high level overview of the API resources. Example text is shown below:
Standard REST methods are supported on the API, which include POST, GET, and DELETE operations through HTTPS. All payloads to and from the REST interface must be in JSON format. Below is high-level description of the API resources:
User - Represents an Agent, Supervisor or Administrator
- Get User Details
- Change User state (for example, Sign In, Sign Out, Ready, Not Ready, and so on.)
- Get User's Dialogs
Queue - Represents a queue (or skill group in Unified CCE)
- Get Queue Details
- Get List of Queues for a User
> Provide links to setup a base URL. Example text is shown below
Base URL
Every API request will begin with the following base URL.
https://api.xyzdashboard.io/api/v1
> If you have a Sandbox, provide the Sandbox link so that developers can try out the API. For more information, provide a link to Developer Resources page, where user can find more information in the "Sandbox" section. Example text is shown below.
Sandbox
DevNet provides free hosted development environments, known as DevNet Sandboxes, for integrating and working with Cisco technologies. You can try out the API using reservation-based sandboxes (privately configured for you) or always-on sandboxes (publicly configured, but with limited access). View the list of available XYZ Sandboxes.
> Provide example for authentication. Example text is shown below
Authorization
In addition to the path URL, an Authorization header must be added to every API request with the following format.
... show how to do this using cURL and Python ...
Read more about authenticating, including generating an API token here.
> To use certain API, user need to enable the API by logging into the product dashboard. In that case, provide step-by-step instruction on how to login to the product and enable the API. For example, refer to Cisco Identity Services Engine API Reference Guide.
> Then, write the top three things you can do with the API. For example, find a user, start chatting with the user, or create a new room to chat in. Or maybe you want to discover a configuration, load a new configuration, and deploy a changed configuration. Whatever it is your users want to do right away with your API, give them quick examples to try out.
1. Obtain a List of Networks
To begin navigating the API, you will first need to obtain a list of networks. This will be required for the next steps...
Request
... step-by-step continues for your API ...
Response
... show an example response ...
2. Retrieve the Details of a Network
Using the response from the previous step of listing networks, retrieve the details of a network instance...
Request
... step-by-step continues for your API ...
Response
... show an example response ...
3. Modify a Network
Using the identifier from the network retrieved previously, modify it so that the description is different....
Request
... step-by-step continues for your API ...
Response
... show an example response ...
4. Retrieve the Updated Details of a Network
Finally, retrieve the updated details of a network to see the recent modifications...
Request
... step-by-step continues for your API ...
Response
... show an example response ...
> Offer Postman Collections if there's a group of easy tasks to try.
Try It Out Using Postman Collections
Prefer to use Postman rather than code or the command line? Check out our Postman Collections.
> Additional resources and Cisco product examples: