## Overview The NuBot Platform features a full fledged [RESTful](http://en.wikipedia.org/wiki/RESTful) API giving our users the ability to programmatically interact with the platform. Some noteworthy use cases include: * Launch a Test Session from a build process; * Get raw test session date to provide trend analysis over time; * Gather metrics to be displayed on a web dashboard; * Collect information to be sent to third-party components such as Splunk, Logstash, Flume, or Graphite; * Set SNMP traps based on status API requests; ## API in a Nutshell Every user has access to our web API. In fact, our Eclipse ITE Plug-In leverage this API to communicate with our server. Upon registration, you have been assigned an API end-point (e.g., URI) which represents the API base path. Such URI should have the following form: https://nubot.io/prod/api/v0.1 ### Authentication Along with the URI, your registration details contain authentication credentials in the form of an API key. Our web API uses a **Bearer** token to identify which is part of the broader [OAuth2 open standard authorization specification](https://en.wikipedia.org/wiki/OAuth) scheme over an SSL-encrypted HTTP connection. Hence, whatever the HTTP agent you intend to use, the authentication method remains the same. For instance, using [cURL](http://en.wikipedia.org/wiki/CURL), the following can be used: curl -H 'Authorization: Bearer <apiKey>' https://nubot.io/prod/api/v0.1/status/ping where `<apiKey>` is your account API key that you received by email. The API key can also be seen by logging into the dashboard at <https://nubot.io> and going to on the account page (<https://nubot.io/#account>). #### X-nuecho-site Some part of our API still uses a legacy required HTTP headers to identify organization you're bound to. Not all entry points need the special header but must do. To prevent difficult to diagnose problem while using the API, we strongly suggest to always add this special HTTP header to all requests. Having it where not necessary doesn't hurt anyway. The HTTP header name is `X-nuecho-site` while the value is the your organization id. The organization id can be seen by logging into the dashboard at <https://nubot.io> and going to the account page (<https://nubot.io/#account>). For example, when using `cURL`, you should do: curl -H 'Authorization: Bearer <apiKey>' -H 'X-nuecho-site: <id>' https://nubot.io/prod/api/v0.1/status/ping where `<apiKey>` is your account API key and `<id>` the organization id found on the account page on the NuBot dashboard. #### Note Obviously, you're far from being restricted to cURL. There are many HTTP client libraries out there for any programming languages, from Ruby, Perl, or Python, to Java or PHP. Which language are you using? [Let us know](mailto:nubot-support@nuecho.com)! ## Services Our platform is layered on top of several services, each one dealing with specific tasks. | Service | Description | |---------------------------------|------------------------------------------------------------------------------| |**status** | Provides meta information about the platform. | |**[operations](operations)** | Is responsible for launching and monitoring any ongoing test session. | |**[resources](resources)** | Manages the test resources used at runtime. | |**[results](results)** | Accumulates data about every single test session call. | |**[audio](audio)** | Stores audio resources used by test case scenarios. | |**recording** | Provides access to full call recording. | |**analytics** | Responsible for crunching analytical statistics regarding past test sessions.| |**telephony** | Provides low-level interaction with the underlying telephony platform. | Each service name can be used to forge an URL request, interacting with the platform. ### Generalities While independent, each and every service features a series of common `GET` methods: | Method | Description | |-----------|------------------------------------------------------------------------------------------| |**ping** | returns if the service is up and running. | |**meta** | returns meta information about the service. | #### Important Aside from our **resources** service which supports XML content type (`application/xml`), all of our services support [JSON](http://en.wikipedia.org/wiki/Json) content type (`application/json`) for both requests and responses.