NSO: REST API について

[Akira Iwamoto]

• REST API とは
• REST API vs. RESTCONF
• URI と Resources
• HTTP メソッド
• Query パラメータ
• REST API の使用例
• REST QUERY API
• クエリ（検索式の送信）
• フェッチ(検索結果の取得)
• HTTP Status Code

REST API とは

REST API (又は、RESTful API) は、NSO がサポートする Northbound APIs の一つで、クライアントはHTTP(S)  を使用して、NSOを操作することが出来ます。

REST API 自体は、NSO に限らず他製品でも使用されており、また Javascript からの呼び出しもしやすいため、Webポータルなどでもよく使用されています。

Payload として、NSOでは JSON 又は XML を使用することが可能です。HTTP ヘッダに含める Content-type の指定により、クライアントアプリケーションから使いやすい方を使うことが可能です。

REST API vs. RESTCONF

REST API と RESTCONF は、名前は似ていますが直接関係はありません。RESTCONF は RFC 8040 で定義されていますが、REST API自体には標準化された仕様は無く、NSO（又はREST APIをサポートするソフトウェア）で独自実装しています。

なお、NSO では、RESTCONF プロトコルを NSO 4.3 以降でサポートしています。

ここでは、REST API について紹介しています。

URI と Resources

REST API では、URI で特定可能なオブジェクト（ノード）に対して、何らかの操作を行います。それぞれのオブジェクトは、いずれかのリソースに所属しています。

http://x.x.x.x:8080/api/<resource>

API リソースとして、以下が定義されています。

FieldDescription

version	REST API のバージョン
config	config リソース (running の別名)
running	running リソース
operational	operational リソース
operations	YANG rpc や、NSO action 等の、定義されたoperations コンテナ
rollbacks	ロールバックファイルコンテナ

(NSO 4.4 Northbound APIs マニュアルより)

URI の例

http://localhost:8080/api/running

http://localhost:8080/api/operations

HTTP メソッド

NSO では、以下のメソッドをサポートしています。

メソッド	説明
GET	オブジェクトの取得を行います
POST	リストインスタンスの新規作成を行います
PUT	オブジェクトの新規作成、又は変更（置換）を行います
PATCH	オブジェクトの変更を行います
DELETE	オブジェクトの削除を行います
HEAD	GET使用時のヘッダ情報のみを取得します。
OPTIONS	指定したリソースで使用可能なメソッド一覧を取得します

Query パラメータ

URIに?記号に続けて、クエリパラメータを付加することで、通常の動作を変更し、色々な動きをさせることが出来ます。なお、この後で説明します REST Query API とは関係はありません。

例えば、commit アクションに対して、"commit dry-run" を行いたい場合にも、クエリパラメータを使用します。

クエリパラメータには種類が多く定義されているため、一部を紹介致します。他のパラメータについては、マニュアルの以下を参照下さい。

NSO 4.4 Northbound APIs  -> The REST API -> Getting started -> Query Parameters

dryrun	データ変更時、commit dry-run 相当を行います。Southbound 機器、CDBへの変更を一切行わず、変更されるデータの計算のみを行います。
no-networking	データ変更時、commit no-networking 相当を行います。Southbound 機器への変更はせず、CDB の変更のみ行います。
with-defaults	データ取得時、show running-config | detail 相当を行います。取得データに、デフォルト値を含めます。

REST API の使用例

curl コマンドを使用した例を以下に示します。

/api に対して OPTIONS コマンドを発行しています。GET と HEAD メソッドが使用可能であることがわかります。

$ curl -i -X OPTIONS http://localhost:8080/api -u admin:admin
HTTP/1.1 200 OK
Server:
Allow: GET, HEAD
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 0
Content-Type: text/html
Pragma: no-cache
$

/api へ GET  メソッドを使用した例です。/api 以下にあるリソースを取得出来ました。なお、curl コマンドでは、-X でメソッドを指定出来ますが、GETはデフォルト設定ですので、明示的に指定する必要はありません。-i オプションで、ヘッダを表示しています。

デフォルトの取得データフォーマットは、XMLです。 

$ curl -i -X GET http://localhost:8080/api -u admin:admin
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 07:23:06 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 181
Content-Type: application/vnd.yang.api+xml
Vary: Accept-Encoding
Pragma: no-cache

<api xmlns="http://tail-f.com/ns/rest" xmlns:y="http://tail-f.com/ns/rest">
 <version>0.5</version>
 <config/>
 <running/>
 <operational/>
 <operations/>
 <rollbacks/>
</api>
$

同じ結果を、JSON で取得している例です。Accept ヘッダで受信するMIME を変更することで、実施しています。

$ curl -i -X GET http://localhost:8080/api -u admin:admin -H "Accept: application/vnd.yang.api+json"
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 07:29:34 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 98
Content-Type: application/vnd.yang.api+json
Vary: Accept-Encoding
Pragma: no-cache

{"api":{"version":"0.5","config":{},"running":{},"operational":{},"operations":{},"rollbacks":{}}}
$

running リソース上の、aaa オブジェクトを取得しています。CLI 上の "show running-config aaa" と同等です。aaa 以下に存在するリスト(= user)  まで表示しています。詳細が必要な場合は、URI に ?deep を添付します。

$ curl -i -X GET http://localhost:8080/api/running/aaa -u admin:admin
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 07:33:45 GMT
Last-Modified: Wed, 19 Apr 2017 11:24:25 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1493-188275-346474
Content-Type: application/vnd.yang.data+xml
Transfer-Encoding: chunked
Pragma: no-cache


<aaa xmlns="http://tail-f.com/ns/aaa/1.1" xmlns:y="http://tail-f.com/ns/rest" xmlns:aaa="http://tail-f.com/ns/aaa/1.1">
<authentication>
<users>
 <user>
  <name>admin</name>
 </user>
 <user>
  <name>oper</name>
 </user>
 <user>
  <name>private</name>
 </user>
 <user>
  <name>public</name>
 </user>
</users>
</authentication>
</aaa>

aaa オブジェクトに定義されている、ユーザを追加する例です。POSTメソッドで、/aaa/authentication/users/user リストにユーザ test が追加されます。

ここでは、JSON Payload  を使用しています。

$ curl -i -X POST http://localhost:8080/api/running/aaa/authentication/users -u admin:admin -H "Content-Type: application/vnd.yang.data+json" -d '
{ "tailf-aaa:user": {
 "name" : "test",
 "uid" : "0",
 "gid" : "0",
 "password" : "",
 "ssh_keydir" : "",
 "homedir" : ""
 }
}'
HTTP/1.1 201 Created
Server:
Location: http://localhost:8080/api/running/aaa/authentication/users/user/test
Date: Thu, 27 Apr 2017 07:56:08 GMT
Last-Modified: Thu, 27 Apr 2017 07:56:08 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1493-247351-147821
Content-Length: 0
Content-Type: text/html
Pragma: no-cache
$

作成したユーザ test を削除する場合の、dry-run 例です。

$ curl -i -X DELETE http://localhost:8080/api/running/aaa/authentication/users/user/test?dryrun=cli -u admin:admin
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 10:03:15 GMT
Last-Modified: Thu, 27 Apr 2017 08:38:55 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1493-249943-225197
Content-Length: 375
Content-Type: text/xml
Vary: Accept-Encoding
Pragma: no-cache

<dryrun-result xmlns='http://tail-f.com/ns/rest/dryrun'>
<cli>
<local-node>
<data>
 aaa {
     authentication {
         users {
-            user test {
-                uid 0;
-                gid 0;
-                password "";
-                ssh_keydir "";
-                homedir "";
-            }
         }
     }
 }

</data>
</local-node>
</cli>
</dryrun-result>
$

作成したユーザ test を削除する例です。

$ curl -i -X DELETE http://localhost:8080/api/running/aaa/authentication/users/user/test -u admin:admin
HTTP/1.1 204 No Content
Server:
Date: Thu, 27 Apr 2017 08:01:55 GMT
Last-Modified: Thu, 27 Apr 2017 08:01:55 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Etag: 1493-247701-159346
Content-Length: 0
Content-Type: text/html
Pragma: no-cache
$

NSO に登録されているデバイス c0 に対して、sync-from アクションを実行させる例です。operations リソースを使用します。

$ curl -i -X POST http://localhost:8080/api/operations/devices/device/xr532/sync-from -u admin:admin
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 08:42:53 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 76
Content-Type: application/vnd.yang.operation+xml
Vary: Accept-Encoding
Pragma: no-cache

<output xmlns='http://tail-f.com/ns/ncs'>
 <result>true</result>
</output>
$

running リソースを使用する場合、_operationsタグを使って実行することも可能です。

$ curl -i -X POST http://localhost:8080/api/running/devices/device/c0/_operations/sync-from -u admin:admin
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 08:40:23 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 76
Content-Type: application/vnd.yang.operation+xml
Vary: Accept-Encoding
Pragma: no-cache

<output xmlns='http://tail-f.com/ns/ncs'>
 <result>true</result>
</output>
$

REST APIの使用例が、他にもドキュメント中にありますので、必要に応じて参照して下さい。

REST QUERY API

REST Query API は、これまで説明してきたREST APIとは使用目的が異なります。REST APIでは、特定のオブジェクトに対して、情報の取得、作成、更新、削除などを行いいましたが、REST Query API は、情報を検索するためのAPIです。

検索のためには、検索式やキーワードが必要です。決められたフォーマットに沿ってそれらを送ることで、検索結果を取り出すことが出来ます。

POSTメソッドを以下のURIへ発行することで使用出来ます。

http://localhost:8080/api/query

クエリ（検索式の送信）

クエリは、"http://tail-f.com/ns/tailf-rest-query" 名前空間上に定義された、start-query コンテナを使用します。

クエリ例

foreach 以下には、XPATH を使用することが可能です。ここでは、user name が admin のオブジェクトを検索しています。(XPATH 1.0 の対応となります。XPATH 2.0 以降は対応しておりません)

<start-query xmlns="http://tail-f.com/ns/tailf-rest-query">
 <foreach>
 /aaa/authentication/users/user[name = "admin"]
 </foreach>
 <select>
 <expression>name</expression>
 <result-type>string</result-type>
 </select>
 <select>
 <expression>homedir</expression>
 <result-type>string</result-type>
 </select>
 <sort-by>name</sort-by>
 <limit>100</limit>
 <offset>1</offset>
</start-query>

実行例

$ curl -i -X POST http://localhost:8080/api/query -u admin:admin -d '
> <start-query xmlns="http://tail-f.com/ns/tailf-rest-query">
> <foreach>
> /aaa/authentication/users/user[name = "admin"]
> </foreach>
> <select>
> <expression>name</expression>
> <result-type>string</result-type>
> </select>
> <select>
> <expression>homedir</expression>
> <result-type>string</result-type>
> </select>
> <sort-by>name</sort-by>
> <limit>100</limit>
> <offset>1</offset>
> </start-query>
> '
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 09:04:56 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 125
Content-Type: application/yang-data+xml
Vary: Accept-Encoding
Pragma: no-cache


 <start-query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
 <query-handle>4</query-handle>
 </start-query-result>
$

他に、例えば、name に adminが含まれるものを検索する場合は、foreachタグ内のXPATH で、contains 関数を使用して以下の様に指定可能です。

Reference: https://www.w3.org/TR/xpath/#section-String-Functions

/aaa/authentication/users/user[contains("admin", name)]

検索処理には時間がかかる場合があります。上記クエリを実行した時点で検索が開始され、それを取得するために必要な、query-handle が返却されます。

フェッチ(検索結果の取得)

返却された query-handle を使用して、結果を取得します。送信するデータは、start-query-resultコンテナのフォーマットを使用します。

<fetch-query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
  <query-handle>4</query-handle>
</fetch-query-result>

実行結果です。

$ curl -i -X POST http://localhost:8080/api/query -u admin:admin -d '
> <fetch-query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
> <query-handle>4</query-handle>
> </fetch-query-result>
> '
HTTP/1.1 200 OK
Server:
Date: Thu, 27 Apr 2017 09:10:33 GMT
Cache-Control: private, no-cache, must-revalidate, proxy-revalidate
Content-Length: 233
Content-Type: application/yang-data+xml
Vary: Accept-Encoding
Pragma: no-cache


 <query-result xmlns="http://tail-f.com/ns/tailf-rest-query">
 <result>
 <select>
 <value>admin</value>
 </select>
 <select>
 <value>/var/ncs/homes/admin</value>
 </select>
 </result>
 </query-result>
$

HTTP Status Code

いずれのHTTP リクエストを送信した場合でも、返答にはステータスコードが付加されています。NSO 4.4 で定義されているものは、以下があります。

Code Text 説明

200	OK	リクエストが正常処理され、要求された内容が返答内容に含まれます。
201	Created	新たなリソース（インスタンス）が作成されました。Location ヘッダには、そのオブジェクトのURIが含まれています。
204	No Content	リクエストが正常処理されました。返答内容は空です。
400	Bad Request	リクエストの内容に問題があるため、異常終了しました。
401	Unauthorized	認証に失敗しました。
403	Forbidden	リクエストされたオブジェクトへのアクセスが、承認されませんでした。
404	Not Found	リクエストされたオブジェクトが存在しませんでした。
405	Method Not Allowed	リクエストされたメソッドは、このリソースへは許可されていません。
406	Not Acceptable	"Accept" ヘッダや、"format" クエリパラメータで指定されたフォーマットで、処理結果の返答内容を生成出来ません。
409	Conflict	作成しようとしたオブジェクトは、すでに存在しています。
415	Unsupported Media Type	リクエストされたメディアタイプ（MIMEフォーマット）はサポートされていません。
500	Internal Error	何らかのエラーが発生しました。
501	Not Implemented	リクエストされた内容は、実装されていません。
503	Unavailable	リクエストされたオブジェクトに対しての処理は、それが使用中、又はサーバ負荷高などの理由により、完了できません。

(NSO 4.4 Northbound APIs マニュアルより)