Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
icinga-migration opened this issue Apr 17, 2015 · 29 comments
Closed

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

icinga-migration opened this issue Apr 17, 2015 · 29 comments
Milestone

Comments

@icinga-migration
Copy link
Member

@icinga-migration icinga-migration commented Apr 17, 2015

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
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented May 19, 2015

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

  • Estimated Hours set to 40
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Aug 28, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 24, 2015

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

  • Priority changed from Normal to High
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 25, 2015

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

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

@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 28, 2015

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

  • Change /v1/ to /v1/objects/
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 28, 2015

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

  • Document permissions
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 28, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Sep 29, 2015

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

  • Done % changed from 0 to 50
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 19, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 22, 2015

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

TODO:

  • filter_vars
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 27, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 27, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 28, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Oct 29, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 1, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 1, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 1, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 1, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 4, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 4, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 5, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 5, 2015

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

$ ./update-links.py *.md
Unmatched anchor: Downtimes
Unmatched anchor: Downtimes
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 6, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 6, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 6, 2015

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

The above is done.

@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 6, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 8, 2015

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
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 9, 2015

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

  • Status changed from Assigned to Resolved
@icinga-migration
Copy link
Member Author

@icinga-migration icinga-migration commented Nov 12, 2015

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

  • Backport? changed from TBD to No
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
1 participant
You can’t perform that action at this time.