From cfd2f784c23d6665a52a00a5ee5144a5a818c72b Mon Sep 17 00:00:00 2001 From: Gerhard Jungwirth Date: Mon, 28 Sep 2015 11:59:55 +0200 Subject: [PATCH] MT#15393 improve API documentation Change-Id: I7c62a88b14fb24e0fa27b0712cdf6c7cc991b4db --- share/templates/api/root.tt | 2 +- share/templates/api/root/auth.tt | 4 +++- share/templates/api/root/collection.tt | 8 ++++---- share/templates/api/root/intro.tt | 7 +++++-- share/templates/helpers/api_command.tt | 4 ++-- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/share/templates/api/root.tt b/share/templates/api/root.tt index 0a7ddca3ed..297bb38458 100644 --- a/share/templates/api/root.tt +++ b/share/templates/api/root.tt @@ -1,5 +1,5 @@ - + Sipwise NGCP HTTP API documentation diff --git a/share/templates/api/root/auth.tt b/share/templates/api/root/auth.tt index 6dc6834c8c..451b866f55 100644 --- a/share/templates/api/root/auth.tt +++ b/share/templates/api/root/auth.tt @@ -24,7 +24,9 @@ With cURL, use --user 'username:password' option to specify your ac curl -i -X GET --user 'myuser:mypassword' https://example.org:1443/api/ -Additionally use the --insecure option if you are testing against a self-signed server certificate. +Additionally use the --insecure option if you are testing against a self-signed server certificate.
+Read the Part SSL Certificates under the Chapter Security and Maintenance in the SPCE documentation +for more information about SSL Certificates.

Using Perl LWP::UserAgent
diff --git a/share/templates/api/root/collection.tt b/share/templates/api/root/collection.tt index b8f2768914..8e40af2ab8 100644 --- a/share/templates/api/root/collection.tt +++ b/share/templates/api/root/collection.tt @@ -112,7 +112,7 @@ Accept-Post: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/#re [% IF col.actions.grep('^GET$').size -%] Request the entire [% id %] collection -

+

You cannot request the entire collection at once, but instead you can simply page through the results. The response provides prev and next links you can follow to get the next page. @@ -179,7 +179,7 @@ Content-Type: application/hal+json; profile="http://purl.org/sipwise/ngcp-api/" INCLUDE helpers/api_req_res.tt request=request response=response level=level+3; -%] -

+

[% END -%] [% IF col.item_actions.grep('^GET$').size -%] @@ -281,7 +281,7 @@ Preference-Applied: return=minimal'; [% IF col.item_actions.grep('^PATCH$').size -%] Update specific fields of an existing [% id %] item -

+

[% props = ''; rem = 0; rep = 0; FOREACH p IN col.fields; @@ -398,7 +398,7 @@ Preference-Applied: return=minimal'; INCLUDE helpers/api_req_res.tt request=request response=response level=level+3; -%] -

+

[% END -%] [% IF col.item_actions.grep('^DELETE$').size -%] diff --git a/share/templates/api/root/intro.tt b/share/templates/api/root/intro.tt index b76556b673..f19d8ef32e 100644 --- a/share/templates/api/root/intro.tt +++ b/share/templates/api/root/intro.tt @@ -77,15 +77,18 @@ Some collections define query paramters to filter the output. Typical use cases Query parameters are appended to the URL like in the following example: -curl -X GET 'https://example.org:1443/api/somecollection/?param_one=1&param2=something +curl -X GET 'https://example.org:1443/api/somecollection/?param_one=1&param2=something' Some query parameters allow wildcard/pattern matching, which is expressed by a '*' like this: -curl -X GET 'https://example.org:1443/api/somecollection/?param=*something* +curl -X GET 'https://example.org:1443/api/somecollection/?param=*something*' +Note: this examples do not yet contain authentication and will therefore not work on a standard installation. To read more +about that go to the Chapter Authentication. + HTTP Response Codes The REST API returns an HTTP response code with the following classes: diff --git a/share/templates/helpers/api_command.tt b/share/templates/helpers/api_command.tt index c637f92765..01162c9f24 100644 --- a/share/templates/helpers/api_command.tt +++ b/share/templates/helpers/api_command.tt @@ -3,12 +3,12 @@ [% IF extended -%]

- Note that you MUST pass the following additional headers for this request: + You can pass the following additional headers for this request: