2022-09-22 15:50 1/2 XchRest API

Table of Contents
XchRest API ....................................................................................................................................... 1
Introduction ................................................................................................................................... 1
OAuth ............................................................................................................................................ 1
URL and Schema ........................................................................................................................... 1
Port 8880 ...................................................................................................................................... 2
Postman setup ............................................................................................................................... 2
Environment variables .................................................................................................................. 2
Collection ...................................................................................................................................... 2
OAuth token setup ........................................................................................................................ 3
GET Jobs request ........................................................................................................................... 3

Technical documentation - http://wiki.netyce.com/

Last update: 2022-09-19 08:44 guides:user:xchrest http://wiki.netyce.com/doku.php/guides:user:xchrest

http://wiki.netyce.com/ Printed on 2022-09-22 15:50

2022-09-22 15:50 1/5 XchRest API

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.

Technical documentation - http://wiki.netyce.com/

Last update: 2022-09-19 08:44 guides:user:xchrest http://wiki.netyce.com/doku.php/guides:user:xchrest

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

http://wiki.netyce.com/ Printed on 2022-09-22 15:50

2022-09-22 15:50 3/5 XchRest 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 name Value Example

Token Name xchrest
Grant Type Client Credentials
Access Token
{{xch_uri}}/api/oauth/access_token https://genesis/netyce.org:8880/api/oauth/access_token
URL
Client ID {{xch_client_id}} ServiceOrderAPI
Client Secret {{xch_client_secret}} ServiceOrderAPI
Scope not used
Client
Send as Basic Auth header
Authentication

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

Technical documentation - http://wiki.netyce.com/

Last update: 2022-09-19 08:44 guides:user:xchrest http://wiki.netyce.com/doku.php/guides:user:xchrest

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:

Method Value Example

GET {{xch_uri}}/{{xch_path}}/job https://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": "nms@acme.com",
"job_id": "0919_0003",
"notify": "",
"prev_state": "-1",
http://wiki.netyce.com/ Printed on 2022-09-22 15:50
2022-09-22 15:50 5/5 XchRest API

"state": 3,
"user": "nmsoper",
"user_email": "nms.operator@acme.com",
"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": ""
}
},

From:
http://wiki.netyce.com/ - Technical documentation

Permanent link:
http://wiki.netyce.com/doku.php/guides:user:xchrest

Last update: 2022-09-19 08:44

Technical documentation - http://wiki.netyce.com/