User Tools

Site Tools


guides:user:xchrest

XchRest API

Introduction

XchRest is the RESTful API to the NetYCE system. It is set to supersede the existing xml-based Xch API. This XchRest API will gradually expose more and more of the functions that were already available using the Xch API, but at the same time expose these functions as endpoints to objects like nodes, nccm, jobs, etc. It is using CRUD manipulations (Create, Read, Update, Delete) with regular REST http(s) methods (Get, Post, Patch, Put, Delete). XchRest will use JSON formatted requests and responds in kind.

OAuth

Authentication uses OAuth tokens for which an OAuth 2.0 server is built in. This server will issue a token on request using the NetYCE user-accounts for authentication (user-name and user-password) and authorization (user-group and user-level).

This token must be retrieved prior to any API request and has a limited time-to-live. This time-to-live is default 600 seconds (10 minutes), but its implementation is such that it is handled as an idle-timeout: the time-to-live is reset on every request. The token expires only after 10 minutes of inactivity.

URL and Schema

The XchRest API will use port 8880 by default which can be customized on setup. The build-in documentation (schema) can be consulted using the URL

  https://<server-fqdn>:8880/schema

Use 'http' when the system is not configured for SSL.

API requests will have to use the path /api/xch/v1 as the base for each endpoint, like the example below for the 'job' endpoint

  https://genesis.netyce.org:8880/api/xch/v1/job

This schema is shown as a rendering of the OpenAPI / Swagger documentation file that can also be found at the server using the path /opt/yce/mojo/lib/XchRest/Resource/xch_rest_schema.yaml.

Port 8880

The default port number can be changed in the setup session using the yce_setup.pl script. When configuring the roles of each server in the NetYCE environment a prompt request to confirm or override the port number of XchRest.

It is not allowed at this point to choose 8080 or 8443 as those ports are in use by the backend API that supports the GUI. This backend API is not available to customers.

Postman setup

The application “Postman” is often used to familiarize with an API or to perform ad-hoc requests and is therefore a suitable environment to clarify the use of the OAuth tokens and the various endpoints available within the API.

Environment variables

The Easiest way to setup Postman (or any other API tool, e.g 'Insomnia') is to create a set of environment variables for those server specific values. Because the Postman tool will substitute these variables, there will be no need to do these substitutions manually while copying the settings in the examples.

From the main menu select “Workspaces” and create a new workspace named “XchRest”. Then select “Environments” at the left and create one named after the NetYCE server. You will have to rename it after it is created using the elipses (…).

Then add the following set of variables. Chose values corresponding to your server. As the xch_client_id must match an existing NetYCE user-id, you can select an existing user or create a dedicated api user. In the example we use the 'ServiceOrderAPI' user that added for this purpose. Set an appropriate password. The user-level should be manager or modeler.

Remember to save these settings or Postman will not use them. Also make sure the environment name is selected, a solid checkbox after its name.

Collection

Next, a “collection” must be created. It will contain the the defined requests to use against the XchRest API. Create a collection named “XchRest”. Again, change the name after it is created.

Select it and chose the “authorization” tab. Here the OAuth 2.0 token request will be defined. When executed, a token will be fetched from the server and stored for further use in the collection. Any API request in the collection can then use this token if referenced.

OAuth token setup

In the Authorization tab of the XchRest collection, the authorization “Type” must be set to “OAuth 2.0”.

The OAuth 2 configuration options then must be entered. For XchRest, the “Grant type” must be set to “Client Credentials” which are to be presented to the “Access Token URL”. This URL uses the path “/api/oauth/access_token”.

The “Client ID” and “Client Secret” refer to the NetYCE user-id and password. This NetYCE user-id can be a local user or ldap/ad user and must be an active account (not expired and logged in at least once). These credentials must be “Send as Basic Auth header”.

When using the Environment Variables defined earlier, the following values can be used:

Option nameValueExample
Token Namexchrest
Grant TypeClient Credentials
Access Token URL{{xch_uri}}/api/oauth/access_tokenhttps://genesis/netyce.org:8880/api/oauth/access_token
Client ID{{xch_client_id}}ServiceOrderAPI
Client Secret{{xch_client_secret}}ServiceOrderAPI
Scope not used
Client AuthenticationSend as Basic Auth header

Remember that each tab in Postman has a “Save” option. Unsaved variables are not used and unsaved configurations are lost on restart.

With this setup, a token can be requested using the “Get New Access Token” button. Click “Use Token” to add it to the collection.

GET Jobs request

As a basic fetch example, the 'Job' listing serves as a good starting point. In the XchRest collection add a new request (right click the elipses (…) of the collection and choose “New Request”. This will create a GET request bu default. Rename it to “Jobs”.

Select the “authorization” tab and set the “type” to “Inherit auth from parent”. This will allow this request to use the OAuth token fetched by the collection to be included in the request.

For the request, enter the GET URL for the “job” request:

MethodValueExample
GET{{xch_uri}}/{{xch_path}}/jobhttps://genesis.netyce.org:8880/api/xch/v1/job

The transaction is executed by clicking the “Send” button“. If the request did not include a valid token, the resulting JSON message lists a 401 “Unauthorized” error. As the token expires in 10 minutes, a new token must be fetched when this error is received.

The response on a valid request will look like this:

The response shows the use of paging as the default page-length is 50 entries. The returned list of scheduled jobs is found in the “result” array which is shown here in its collapsed form.

Note that the page length can also be set in the request by including variable l. The start of the page is set using the variable s. A filter variable can be used to select specific entries. See the schema documentation for details.

For each job currently scheduled the result array will include a 'job' structure:

        {
            "commands": [
                "#",
                "# Some job commands",
                "#"
            ],
            "job": {
                "approver": "",
                "approver_level": null,
                "audit_level": "3456",
                "auditor": "",
                "duration": "",
                "group": "NetYCE",
                "group_email": "[email protected]",
                "job_id": "0919_0003",
                "notify": "",
                "prev_state": "-1",
                "state": 3,
                "user": "nmsoper",
                "user_email": "[email protected]",
                "user_level": "4",
                "user_name": "NMS Operator"
            },
            "parameters": {
                "change_id": "",
                "client_type": "CMDB",
                "domain": "CPE_mgmt",
                "node": "asd-er-frw010",
                "node_addr": "asd-er-frw010.mgmt.acme.com",
                "node_fqdn": "asd-er-frw010.mgmt.acme.com",
                "node_name": "asd-er-frw010",
                "vendor_type": "PaloAlto_panos",
                "verbose": "-v"
            },
            "scenario": [
                "Description asd-er-frw010 Basic command job...",
                "task = Basic_cmd_job",
                "end"
            ],
            "schedule": {
                "queue": "yce",
                "scheduled": "Tue 20-Sep-2022 05:05:00",
                "scheduler": "genesis",
                "started": ""
            }
        },
guides/user/xchrest.txt · Last modified: 2022/09/19 08:44 by yspeerte