Quick and dirty API Documentation, needs more heavy documentation but this will give basic routes.

Right now there isn't much in terms of documentation. We are working toward getting there.

Understand the API system is very new, but as much as I could "simply" implemented.

What I mean with this:

  1. Data body or return is done with JSON.
  2. All objects in the core have some ability to managed with the API system with the only exception, so far, being Users.

There are a few important bits in regards to interacting and using the API System.

  1. API Can be globally enabled/disabled.
  2. API Can be user enabled/disabled. -- (You can define which users you want to have access to the api system.)
Tokens:
  1. API Global token is a header required with the name fog-api-token
  2. API User token is a header that can be used (Highly recommended) being passed as a header in the form fog-user-token
  3. You can not manually create the tokens via the presented text fields. This is what the purpose of the "Reset Token" Buttons are. There's a Reset Token for the global API as well as one for each user.
  4. Tokens are cryptographically generated so no two tokens will be known regardless of how many FOG Server's you decide to install. There is no "default" token essentially. This holds true for both User and Main API Tokens.
Authentication:

You can use HTTP Basic Authorization (with curl -u <user>:<password> or header with name Authorization: Basic <base64encoded username:password>
Although I have allowed the ability for this type of authentication, and it will work, I would still recommend using user token system as it cannot be received and decoded to a valid username/password pair to manage your fog server.

Routes and Methods:

GET
  1. /fog/system/info Returns 200 if accessible
  2. /fog/system/status Alias for #1
  3. /fog/<objectactivetasktype>/current Returns listing of "active" items. Active referring task types, (Snapin Task, Snapin Job, Task, Scheduled, Multicast)
  4. /fog/<objectactivetasktype>/active Alias for #3
  5. /fog/<object>/search/<whatareyousearchingfor> Idea is similar to the Search Page from GUI.
  6. /fog/<object> Same idea as "List all"
  7. /fog/<object>/list Alias to #6 (1.4.1)
  8. /fog/<object>/all Alias to #6 (1.4.1)
  9. /fog/<object>/<IDOFOBJECT> Same as if clicking edit on an item (only just to get its information).
  10. /fog/search/<stringtosearch> Will return all matching results of all items, hosts, images, etc... (Essentially a universal search.) (1.5.0)
  11. /fog/unisearch/<stringtosearch> Alias for #10 (1.5.0)
PUT (Requires a json body)
  1. /fog/<object>/<IDOFOBJECT>/edit Update the object.
  2. /fog/<object>/<IDOFOBJECT>/update Alias for #1
  3. /fog/<object>/<IDOFOBJECT> Alias for #1
POST (Requires a json body)
  1. /fog/<objecttasktype>/<IDOFOBJECT>/task Task object.
  2. /fog/<object>/create Create new object.
  3. /fog/<object>/new Alias of #2.
  4. /fog/<object> Alias of #2. (1.4.1)
DELETE
  1. /fog/<objectactivetasktype>/cancel Cancel specific items (requires json body)
  2. /fog/<objecttasktype>/<IDOFOBJECT>/cancel Cancel specific task for object.
  3. /fog/<object>/<IDOFOBJECT>/delete Delete/Remove object.
  4. /fog/<object>/<IDOFOBJECT>/remove Alias of #3
  5. /fog/<object>/<IDOFOBJECT> Alias of #3 (1.4.1)
  1. /fog/system/info Returns 200 if accessible
  2. /fog/system/status Alias for #1

I realize this is not a full on "here's everything" but it's something that should be able to help get you along the path.

Core objects
  1. clientupdater
  2. dircleaner
  3. greenfog
  4. group
  5. groupassociation
  6. history
  7. hookevent
  8. host
  9. hostautologout
  10. hostscreensetting
  11. image
  12. imageassociation
  13. imagepartitiontype
  14. imagetype
  15. imaginglog
  16. inventory
  17. ipxe
  18. keysequence
  19. macaddressassociation
  20. module
  21. moduleassociation
  22. multicastsession
  23. multicastsessionsassociation
  24. nodefailure
  25. notifyevent
  26. os
  27. oui
  28. plugin
  29. powermanagement
  30. printer
  31. printerassociation
  32. pxemenuoptions
  33. scheduledtask
  34. service
  35. snapins
  36. snapinassociation
  37. snapingroupassociation
  38. snapinjob
  39. snapintask
  40. storagegroup
  41. storagenode
  42. task
  43. tasklog
  44. taskstate
  45. tasktype
  46. usercleanup
  47. usertracking
  48. virus
Core task objects
  1. group
  2. host
  3. multicastsession
  4. snapinjob
  5. snapintask
  6. task
Core active task objects
  1. multicastsession
  2. scheduledtask
  3. snapinjob
  4. snapintask
  5. task

Routes that allow filtering with JSON body passed

GET
  1. /fog/<object>
  2. /fog/<objectactivetasktype>/active
  3. /fog/<objectactivetasktype>/current
DELETE
  1. /fog/<objectactivetasktype>/cancel

Plugin's Compatibility.

I have worked relatively hard to implement capability for plugins to also tie in with this. This means hooks can be used to implement API level functionality with plugins or custom elements you'd like to use.

Hook Event Names what core element it ties in with:
  1. API_VALID_CLASSES, variable to adjust is labeled 'validClasses'. Ties in with <object> items.
  2. API_TASKING_CLASSES, variable to adjust is labeled 'validTaskingClasses'. Ties in with items.
  3. API_ACTIVE_TASK_CLASSES, variable to adjust is labeled 'validActiveTasks'. Ties in with items.
  4. API_MASSDATA_MAPPING, variables to adjust are labeled 'data', 'classname', and 'classman'. Operates on the "list" and "search" type routes.
  5. API_INDIVDATA_MAPPING, variables to adjust are labeled 'data', 'classname', and 'class'. Operates on individual objects such as /fog/<object>/<IDOFOBJECT>
  6. API_GETTER, variables to adjust are labeled 'data', 'classname', and 'class'. Operations for all items and is used to present the return of data in a common way regardless of what object is being called.
  • In regards to #6 of the Hook Event elements, think of it as this:
    If I request information about a task, one of the elements of a task is the "host" object. The data presented in the "Task" return for a specific host will look the same in the task return as it would if you looked the host up individually. For example, if the task is using a hostID of 7, the 'host' item in this element would look identical to the return data if you were go to route /fog/host/7
List all active tasks:
header('fog-api-token: <FOG Configuration Page->FOG Settings->API Settings->FOG_API_TOKEN>');
header('fog-user-token: <User management page->relevant user->API Settings->User API Token>');
http://fogserverip/fog/task/active

So let's do this command line style:
Let's just say your api token is abcde
Let's just say your user token is fghij
List all current/active tasks is a GET request.
URL for now is just fogserver

curl -H 'fog-api-token: abcde' -H 'fog-user-token: fghij' -X GET http://fogserver/fog/task/current -o listalltasks.json

This will list all current/active tasks to a file in the current working directory named listalltasks.json

For creating a snapin task, this depends how you plan to do it. To be honest, while the option is available, it's not something I've worked overly hard to get working "natively". It was originally only designed to allow host and group, though I saw the appeal and added capabilities.

So let's just say you have a snapin associated to a host.

The snapin ID is: 6
The host ID is: 1

This would be a POST request as per the earlier information.

The URL you would call would be:

http://fogserver/fog/host/1/task

The post requires some information, and luckily I kind of documented the "maximum" and "minimum" information for creating a tasking in this way.

The "data to send" would be, at minimum:

{
    "taskTypeID": <IDOFTASKTYPETOUSE>
}

For a "snapin" task, this is ID's 12 or 13. important to remember which is a single snapin, vs. all snapin though.

The "full" information you could send for tasking in a manner as above is:

{
    "taskTypeID": <IDOFTASKTYPE>,
    "taskName": "NameToGiveTasking",
    "shutdown": <bool>true/false,
    "debug": <bool>true/false,
    "deploySnapins": <bool>/<IDOFSNAPIN or -1 for all>,
    "passreset": "what to change password if passreset task",
    "sessionjoin": "<SessionNameToJoin>",
    "wol": <bool>
}

In your case, with a specific known host and snapin to send you could do:

curl -H 'fog-api-token: abcde' -H 'fog-user-token: fghij' -H 'Content-Type: application/json' -X POST -d '{"taskTypeID":13,"deploySnapins":6}' http://fogserver/fog/host/1/task

This should create the tasking for you as you described. (Task Type ID 13 = Single Snapin Task, deploy Snapins is true/false/-1 = all/<IDOFSNAPIN>