When creating an API poller, your first step is selecting one of the following methods for the request.
- GET sends a request for data from a URL.
- POST creates a new record.
The method you use for an API request depends on:
- What you want to do, and
- What rights you have.
Similar to how you need different rights to perform various tasks in most applications, you need rights to use different methods against a remote API and get a successful response. For example, to use a GET request to retrieve data from the Orion SDK, no extra rights are required other than the Orion account credentials included in the parent request. However, to send a POST request that creates a new record, you typically require extra rights. For example, to use a POST request that adds a node to the Orion database, your Orion account must have Node Management rights.
GET retrieves data from an API
The most common method for API requests, GET, requests data from a specific location on a server, called an endpoint. If the request is successful, data is returned in a response payload. Most GET requests are required to include some form of authorization in their headers (usually a username and password); check the API documentation for details.
Here is an example of a GET request sent to the Orion API, asking for the names of three Orion polling engines from a specific database table:
When this query is packaged with the rest of the information provided on the API Poller page, including authorization and headers, the entire requests looks like the following:
GET https://localhost:17778/SolarWinds/InformationService/v3/Json/Query?query=SELECT+Uri+FROM+Orion.Pollers+ORDER+BY+PollerID+WITH+ROWS+1+TO+3+WITH+TOTALROWS HTTP/1.1
Authorization: Basic YWRtaW46
User-Agent: curl/7.20.0 (i386-pc-win32) libcurl/7.20.0 OpenSSL/0.9.8l zlib/1.2.3
POST sends data to an API to create or update a resource
Unlike the GET method that requests data from a remote API, the POST method is used to send changes to an API endpoint. These requests typically include additional data in the message body, as opposed to GET request that may include all necessary details in the request URL.
POST requests usually require authentication by the remote API. For example, you can use standard Orion account credentials to send GET requests that retrieve data from the Orion API (for example, to retrieve a list of available nodes), but you need Node Management rights for the Orion Platform to send a POST request (for example, to add a node), as defined on the Manage Accounts page.
POST requests supply additional data to the target in the message body, not the URL. Credentials, if configured for an API poller, are sent in a separate Header file.
Note the following details about API poller requests:
- Allow time for responses. The larger the data set, the longer the response time.
- Dedicated headers are required for pages that require logins.