2.1 How does the API work?
- Laura McWilliams
To access the API, required data are sent to a particular endpoint of the API. Each endpoint is labeled with a URI string (for example, something like “https://MyIsoraURL/api/sheets”).
When sending or requesting data through the API, an HTTP “verb” is used to specify the nature of your request. While these keywords are not always standardized, Isora GRC’s API follows the principles of a “RESTful API” (Representational State Transfer API). Essentially, this means that each keyword has a specific purpose and a predictable result. Not all verbs will be accessible on all endpoints. Along with the verb, API calls may include information about resources stored in the server’s databases. These resources are representations of all the different objects Isora GRC knows about, like hosts, people, organizational units, sheets, etc.
The following table shows a list of the verbs most commonly used in a RESTful API.
GET | Request information about a resource without modifying anything |
POST | Request that the server creates a new resource |
PUT | Request the server to replace (update) a resource |
DELETE | Request the server to remove a resource from Isora GRC |
Table 2.1.1 Common API call verbs
Depending on whether the server accepts your API request, it will reply with either the requested/updated data or an HTTP error message. For example, if a user attempts an operation which is not permitted (for example, an ordinary user attempts an operation which requires super-user access), an “Error 401: Unauthorized” would be returned. There are many other possible error messages.
There are many ways to implement API calls within a programming environment, which gives you great flexibility in choosing how to manage your data. You can therefore customize your workflows based on your needs rather than being forced to work solely through clicking in the web browser interface. Most programming languages have a built-in or easily accessible module to allow for sending and receiving API information by simply plugging in the required authentication, endpoint and data needed to achieve your goals.
If working in a shell environment, built-in commands should allow you to access the API. For example, you could use the “Invoke-RestMethod” command in Windows PowerShell or “curl” in Linux or OS X.
Isora GRC uses authentication tokens to identify API users. This token, which is simply an ascii string, is included in the header of each HTTP message constructed when you make an API call.
Next: 2.2 How do I enable API access?