Improve API docs with examples for each endpoint
SimpleMDM's API documentation (https://api.simplemdm.com/) is inconsistent in what information is included per endpoint. For example, https://api.simplemdm.com/#custom-configuration-profiles shows the response body for a GET call, but the POST (create) section has no usage information. It's up to the user to intuit from other endpoints the format in which those arguments should be.
https://api.simplemdm.com/#custom-attributes shows how to set a value for a device, but not create a new custom attribute globally.
We (the customer) end up making assumptions about API formats which are usually true, but only able to confirm through guessing. It would help to ensure the official docs are correct and up to date.
I'm asking for two improvements...
1.100% example code coverage for every endpoint and action (GET, PUT, PATCH, DELETE)
2. Provide examples in multiple languages - shell, Python, Ruby, Go, JavaScript, and Swift.
-
AdminEric McCann (Admin, SimpleMDM) commented
Thanks Carl! To answer your questions:
Installed Apps:
GET https://a.simplemdm.com/api/v1/installed_apps/{INSTALLED_APP_ID}
Currently this method assumes that you have already called the List Installed Apps for a Device endpoint: GET https://a.simplemdm.com/api/v1/devices/{DEVICE_ID}/installed_apps
and are using one of the listed IDs to get just the specific installed app on that device.
Enrollments:
GET https://a.simplemdm.com/api/v1/enrollments
This returns a list of all enrollments in your account, excluding Automated Enrollments (eg. Group Enrollments and One-Time Enrollments).
Cloning Groups:
POST https://a.simplemdm.com/api/v1/device_groups/{DEVICE_GROUP_ID}/clone
This clones the group but there are currently no arguments supported, which is similar to the behavior if you clone a group in the admin interface. There is currently no API method to update a group name, but that would be a great feature request.We will work on updating the documentation for these endpoints and ensuring they are consistently documented across the board.
-
Carl commented
Bumping this.
The https://api.simplemdm.com/#installed-apps documentation seems to be a bit ambiguous; it reads to me that you should be able to call these methods for a specific device, yet there is nothing that indicates you need to pass a device id parameter, for those methods.
The documentation for https://api.simplemdm.com/#enrollments is sparse - what is this method is actually doing? Are there supposed to be params to specify which enrollment to delete?
The documentation for https://api.simplemdm.com/#device-groups does not indicate if the clone method takes any parameters to set the name of the freshly cloned device group, does this endpoint actually even support changing the name of a device group after/during cloning? Is there an update method for this to modify an existing device group?
I have approx 40 votes left; if I could throw all 40 votes at this I would, but I can only throw 3 at it.