[dev.icinga.com #9105] API Documentation #2934

icinga-migration · 2015-04-17T13:39:18Z

This issue has been migrated from Redmine: https://dev.icinga.com/issues/9105

Created by gbeutner on 2015-04-17 13:39:18 +00:00

Assignee: mfriedrich
Status: Resolved (closed on 2015-11-09 09:17:16 +00:00)
Target Version: 2.4.0
Last Update: 2015-11-12 15:34:38 +00:00 (in Redmine)

Backport?: No
Include in Changelog: 1

Changesets

2015-08-28 15:17:51 +00:00 by mfriedrich d4b3bb5

API: First documentation draft

refs #9105

2015-08-29 08:29:19 +00:00 by mfriedrich 21b021b

Docs: Fix url anchors in API chapter

refs #9105

2015-08-29 08:29:53 +00:00 by mfriedrich f1e37c4

Docs: Remove unused wip chapter

refs #9105

2015-09-28 16:04:42 +00:00 by mfriedrich 30d1fa4

Update the api documentation

Rename /v1/hosts to /v1/objects/hosts.
Add permissions docs.
Change the url endpoints and change the host create/modify/etc
into a generic config object section.

refs #9105

2015-10-08 23:27:08 +00:00 by mfriedrich ccd6b7d

Update documentation

refs #9105

2015-10-19 11:27:20 +00:00 by mfriedrich 30b1407

Documentation: Fix table formatting

refs #9105

2015-10-22 10:14:16 +00:00 by (unknown) 55dda8a

Implement URL handler for /v1

refs #9105

2015-10-22 10:15:32 +00:00 by (unknown) 10bd3ed

Implement URL handler for /v1

refs #9105

2015-10-22 10:18:23 +00:00 by (unknown) b144191

Update documentation

refs #9105

2015-10-22 11:29:31 +00:00 by (unknown) 1b8fd96

Add redirect for /

refs #9105

2015-10-27 07:59:36 +00:00 by (unknown) 263e9d4

Update documentation

refs #9105

2015-10-27 08:50:24 +00:00 by (unknown) 2f2269b

Remove byte order mark in 9-icinga2-api.md

refs #9105

2015-10-27 13:15:07 +00:00 by jflach 2fc042e

Update API actions and documentation

refs #9080 #9105

2015-10-27 17:42:32 +00:00 by mfriedrich 1223007

Review and update documentation

fixes #9080
refs #9105

2015-10-28 06:24:13 +00:00 by (unknown) 4b09302

Fix incorrect URL check in the InfoHandler class

refs #9105

2015-10-28 06:46:04 +00:00 by (unknown) 4763dea

Fix incorrect URL check in the InfoHandler class

refs #9105

2015-10-29 16:31:15 +00:00 by mfriedrich a3e8cf8

Update documentation

refs #9105

2015-10-29 17:59:30 +00:00 by mfriedrich 6f8e25a

Add doc URL to /v1 info page

refs #9105

2015-11-01 12:43:26 +00:00 by mfriedrich 4d3020d

Update API documentation

* Rename object types to config object types
* Add common config object attributes (e.g. version) overview
* add API references to troubleshooting
* add CheckResult and PerfdataValue value types (exposed via API)
* Update object types and their attributes

refs #9105

2015-11-01 15:34:56 +00:00 by mfriedrich 6123377

Update API documentation

See comments in https://dev.icinga.org/issues/9105#note-15

refs #9105

2015-11-01 17:30:46 +00:00 by mfrosch 3134e44

Update API docs for language improvements

refs #9105

2015-11-05 13:41:18 +00:00 by mfriedrich a3d5d24

Update API documentation from feedback and API clients

refs #9105

2015-11-06 10:04:31 +00:00 by mfriedrich 7d3319e

Update API documentation for Accept header

refs #9105

2015-11-06 14:32:44 +00:00 by mfriedrich d370275

Update API documentation for object queries and joins

refs #9105

2015-11-07 08:57:40 +00:00 by (unknown) 315232b

Update documentation

refs #9105

2015-11-07 12:28:09 +00:00 by (unknown) 1a29fa6

Update documentation

refs #9105

2015-11-07 12:37:11 +00:00 by (unknown) ced3412

Update documentation

refs #9105

2015-11-07 12:49:14 +00:00 by (unknown) d975e47

Update documentation

refs #9105

2015-11-08 00:19:38 +00:00 by (unknown) df1d235

Update documentation

refs #9105

2015-11-08 11:54:36 +00:00 by mfriedrich cd3edd9

Update API documentation

refs #9105

2015-11-08 11:55:38 +00:00 by (unknown) 0a23eeb

Update documentation

refs #9105

2015-11-09 09:37:47 +00:00 by mfriedrich e0dab9f

Documentation: Fix example host names

refs #9105
refs #10562

2015-11-09 12:37:08 +00:00 by mfriedrich 390dc92

Update API documentation

refs #9105

2015-11-10 08:57:59 +00:00 by (unknown) 9ef079f

Update documentation

refs #9105

2015-11-10 15:45:52 +00:00 by (unknown) 503826a

Update documentation

refs #9105

The text was updated successfully, but these errors were encountered:

icinga-migration · 2015-05-19T09:03:50Z

Updated by mfriedrich on 2015-05-19 09:03:50 +00:00

Estimated Hours set to 40

icinga-migration · 2015-08-28T08:55:17Z

Updated by mfriedrich on 2015-08-28 08:55:17 +00:00

Status changed from New to Assigned
Assigned to set to mfriedrich

icinga-migration · 2015-09-24T11:26:57Z

Updated by mfriedrich on 2015-09-24 11:26:57 +00:00

Priority changed from Normal to High

icinga-migration · 2015-09-25T08:19:44Z

Updated by jflach on 2015-09-25 08:19:44 +00:00

Note: Use 'icinga.org' and 'localhost' as example urls only

icinga-migration · 2015-09-28T12:51:01Z

Updated by mfriedrich on 2015-09-28 12:51:01 +00:00

Change /v1/ to /v1/objects/

icinga-migration · 2015-09-28T12:51:14Z

Updated by mfriedrich on 2015-09-28 12:51:14 +00:00

Document permissions

icinga-migration · 2015-09-28T16:32:48Z

Updated by mfriedrich on 2015-09-28 16:32:48 +00:00

Done

Permissions
Url endpoints
Query, create, modify, delete config objects

TODOs

More filter examples
Actions
Events

icinga-migration · 2015-09-29T07:38:37Z

Updated by mfriedrich on 2015-09-29 07:38:37 +00:00

Done % changed from 0 to 50

icinga-migration · 2015-10-19T09:41:46Z

Updated by mfriedrich on 2015-10-19 09:41:46 +00:00

Priority changed from High to Normal
Done % changed from 50 to 80

icinga-migration · 2015-10-22T09:40:48Z

Updated by gbeutner on 2015-10-22 09:40:48 +00:00

TODO:

filter_vars

icinga-migration · 2015-10-27T11:11:52Z

Updated by jflach on 2015-10-27 11:11:52 +00:00

TODO:

Explicitly state the differences between url query and json body
Explain how host/hosts works (/v1/objects/hosts?host=host1, /v1/objects/hosts?hosts=host1&hosts=host2)
Additional examples for filters
- "foo" in host.groups
- Do not url encode in the documentation (only once for demonstration purposes)
- filter_vars (only in json body)
Mention and explain X-HTTP-Method-Override
Update existing documentation
Move small chapters into about (Version, Output Format)

icinga-migration · 2015-10-27T17:47:43Z

Updated by mfriedrich on 2015-10-27 17:47:43 +00:00

Done

Move small chapters into about (Version, Output Format)
Action docs reviewed and updated

icinga-migration · 2015-10-28T16:55:57Z

Updated by mfriedrich on 2015-10-28 16:55:57 +00:00

Object Types: Comments, Downtimes and their attributes
API Objects: Comment and Downtime type

icinga-migration · 2015-10-29T16:32:10Z

Updated by mfriedrich on 2015-10-29 16:32:10 +00:00

Done

Object Types: Comments, Downtimes and their attributes
API Objects: Comment and Downtime type
Explain global actions for icingaapplication object

icinga-migration · 2015-11-01T15:35:20Z

Updated by mfriedrich on 2015-11-01 15:35:20 +00:00

Done

filter_vars
X-HTTP-Method-Override
More filters (linux-servers in host.groups)
there's not much to explicitly state for request body and url parameters, but I've rephrased them a little
explain single object and multiple objects with array notation
Update url-encoded requirement, make examples not use url encoded values. The other usage examples should just use the command line working for better copy-pasting URLs. Otherwise users will always stuggle with the documentation examples if they don't have their own success story.

Furthermore I've updated the troubleshooting section linking to the API where possible (e.g. debug check results).

Other than that, there was the following missing:

object types update, including the two value types for CheckResult and PerfDataValue now being exposed via API. Furthermore all config objects now have common attributes such as version, package, etc which must be explained.
Actions examples
- use a single quote for JSON body, and do not escape the double quotes (better readability).
- Remove the ;echo lines. There's "-s" for curl.
- Use real-world examples rather than made-up examples.
- Add missing action examples
- remove-downtime was renamed in the code but not the documentation

Now ALL actions provide an example call, as requested in the original ticket.

icinga-migration · 2015-11-01T17:34:58Z

Updated by mfrosch on 2015-11-01 17:34:58 +00:00

Did a few word corrections :)

We should explain the purpose of the queue attribute in event streams. I can't :)

icinga-migration · 2015-11-01T19:02:13Z

Updated by mfriedrich on 2015-11-01 19:02:13 +00:00

Thanks. I should add a spell checker to vim while typing fast ;)

A general docs review is planned for the upcoming week.

icinga-migration · 2015-11-01T22:19:49Z

Updated by mfriedrich on 2015-11-01 22:19:49 +00:00

TODO

add a chapter about api clients (icinga studio, director)
- add programmatic examples (ruby, perl, python)

icinga-migration · 2015-11-04T09:49:36Z

Updated by mfriedrich on 2015-11-04 09:49:36 +00:00

PS feedback:

Update JSON body example
Actions host/service as parameter
configobject - missing object types (apiuser) - mention that you may use all config objects.
configobjects: order of -k -s -u root:icinga
config packages: s/puppet/example-cmdb/g

icinga-migration · 2015-11-04T14:44:40Z

Updated by mfriedrich on 2015-11-04 14:44:40 +00:00

console cli command
- --connect
- env vars for ICINGA2_API_USERNAME, ICINGA2_API_PASSWORD
- example for getting a check result and command line
- as api client
- permissions - console/*

michi@mbmif ~ $ icinga2 console --connect 'https://root:icinga@localhost:5665/'
Icinga 2 (version: v2.3.11-765-g528083e)
<1> => get_host(NodeName).last_check_result
{
    active = true
    check_source = "mbmif.int.netways.de"
    command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
    execution_end = 1446648335.739059
    execution_start = 1446648331.711726
    exit_status = 0.000000
    output = "PING OK - Packet loss = 0%, RTA = 0.06 ms"
    performance_data = [ "rta=0.064000ms;3000.000000;5000.000000;0.000000", "pl=0%;80;100;0" ]
    schedule_end = 1446648335.739189
    schedule_start = 1446648391.710000
    state = 0.000000
    type = "CheckResult"
    vars_after = {
        attempt = 1.000000
        reachable = true
        state = 0.000000
        state_type = 1.000000
    }
    vars_before = {
        attempt = 1.000000
        reachable = true
        state = 0.000000
        state_type = 1.000000
    }
}
<2> => get_host(NodeName).last_check_result.command
[ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]

Explain --eval

$ icinga2 console --connect 'https://root:icinga@localhost:5665/' --eval "get_host(NodeName).last_check_result.command" | python -m json.tool
[
    "/usr/local/sbin/check_ping",
    "-H",
    "127.0.0.1",
    "-c",
    "5000,100%",
    "-w",
    "3000,80%"
]

icinga-migration · 2015-11-05T14:05:22Z

Updated by mfriedrich on 2015-11-05 14:05:22 +00:00

The above is done, more TODOs:

add required Accept header for !GET requests
- explanation
- update examples

-H 'Accept: application/json'

icinga-migration · 2015-11-05T14:07:12Z

Updated by mfriedrich on 2015-11-05 14:07:12 +00:00

$ ./update-links.py *.md
Unmatched anchor: Downtimes
Unmatched anchor: Downtimes

icinga-migration · 2015-11-06T14:33:26Z

Updated by mfriedrich on 2015-11-06 14:33:26 +00:00

The above is all done.

New TODO:

Object Query structure
- Joins with ?joins=host. or ?all_joins=1
- filter
- meta information is disabled by default (contains used_by,

/v1/objects/Services?meta=used_by&all_joins=1&filter=host.vars.os==%22Windows%22

icinga-migration · 2015-11-06T14:34:05Z

Updated by mfriedrich on 2015-11-06 14:34:05 +00:00

The above is all done.

Remaining tasks:

remove-downtime-by-id -> rename to remove-downtime and require the name attribute in #10512

icinga-migration · 2015-11-06T16:59:13Z

Updated by mfriedrich on 2015-11-06 16:59:13 +00:00

The above is done.

icinga-migration · 2015-11-06T17:12:20Z

Updated by gbeutner on 2015-11-06 17:12:20 +00:00

TODO:

Documentation for /v1/console
Document how to manually set up the API
Explain variable names for joined objects in filter expressions
Script Debugger

 you should explain that you are using curl -k, why this is bad and why client certificates are better (and how to use them)
 read on :P
 that should come as early as possible
 oh, right, we have a few examples before that's explained
 let's fix that
 probably before Request Method override
 or even before the Response part

icinga-migration · 2015-11-08T12:01:26Z

Updated by mfriedrich on 2015-11-08 12:01:26 +00:00

I've removed all real world names and replaced them by example{,2}.localdomain and 192.168.1.{1,2}

icinga-migration · 2015-11-09T09:17:16Z

Updated by gbeutner on 2015-11-09 09:17:16 +00:00

Status changed from Assigned to Resolved

icinga-migration · 2015-11-12T15:34:38Z

Updated by mfriedrich on 2015-11-12 15:34:38 +00:00

Backport? changed from TBD to No

icinga-migration closed this as completed Nov 9, 2015

icinga-migration added enhancement New feature or request area/api REST API labels Jan 17, 2017

icinga-migration added this to the 2.4.0 milestone Jan 17, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[dev.icinga.com #9105] API Documentation #2934

[dev.icinga.com #9105] API Documentation #2934

icinga-migration commented Apr 17, 2015

icinga-migration commented May 19, 2015

icinga-migration commented Aug 28, 2015

icinga-migration commented Sep 24, 2015

icinga-migration commented Sep 25, 2015

icinga-migration commented Sep 28, 2015

icinga-migration commented Sep 28, 2015

icinga-migration commented Sep 28, 2015

icinga-migration commented Sep 29, 2015

icinga-migration commented Oct 19, 2015

icinga-migration commented Oct 22, 2015

icinga-migration commented Oct 27, 2015

icinga-migration commented Oct 27, 2015

icinga-migration commented Oct 28, 2015

icinga-migration commented Oct 29, 2015

icinga-migration commented Nov 1, 2015

icinga-migration commented Nov 1, 2015

icinga-migration commented Nov 1, 2015

icinga-migration commented Nov 1, 2015

icinga-migration commented Nov 4, 2015

icinga-migration commented Nov 4, 2015

icinga-migration commented Nov 5, 2015

icinga-migration commented Nov 5, 2015

icinga-migration commented Nov 6, 2015

icinga-migration commented Nov 6, 2015

icinga-migration commented Nov 6, 2015

icinga-migration commented Nov 6, 2015

icinga-migration commented Nov 8, 2015

icinga-migration commented Nov 9, 2015

icinga-migration commented Nov 12, 2015