Resource Guru API (1.0.0)

Download OpenAPI specification:Download

Overview

This is a REST-style API that uses serialized JSON and OAuth2 authentication. We are very interested in making our API, and this documentation, as good as it possibly can be so please send any feedback to happytohelp@resourceguruapp.com. Any thoughts or suggestions will be gratefully received.

Making Requests

Encoding

The API expects all data to be UTF-8 encoded.

The Base URL

All requests start with the https://api.resourceguruapp.com/ base URL.

  • All requests are done via SSL.
  • All responses are in JSON.

Making a Basic Request

With the exception of Accounts all requests must be prefixed with the Account URL ID.

To make a request for all the Resources on the Example Corp account, the request URL will look something like this https://api.resourceguruapp.com/v1/example-corp/resources.

Rate Limiting

You can perform up to 33 requests per 10 second period on a registered application. If you exceed this limit, you'll get a 429 Rate Limit Exceeded response for subsequent requests. Check the Retry-After header to see how many seconds to wait before retrying the request.

Up to 20 OAuth2 tokens can be issued for a user per minute, and up to 1,000 OAuth2 tokens per day.

CORS

Resource Guru provides headers to allow CORS requests to the API. You will need to authenticate using a valid OAuth2 token.

Response Codes

  • 200 OK
  • 201 Created
  • 204 No Content
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 422 Unprocessable Entity
  • 5xx Resource Guru is having trouble

Authentication

OAuth2 authentication

In order to make authenticated calls to Resource Guru's API, your application must first obtain an OAuth2 access token. To register your app go to https://app.resourceguruapp.com/developers.

Resource Guru implements OAuth2 with the authentication code flow.

Once you have authenticated, you can get information about the authenticated user by calling GET https://api.resourceguruapp.com/v1/me. More details about the request and response are available below.

Getting access to a user's Resource Guru account requires going through a step of authentication. We offer OAuth2 as the standard way to authenticate with our API as this offers a simple flow for users to allow app access without you having to store their credentials.

HTTP Basic authentication

For convenience, Resource Guru's API will accept credentials provided through the HTTP Basic Authorization header. This is intended for exploration of the API only. We apply a global rate limit to HTTP Basic authorizations based on compute resources available at the given time, and provide no SLA. HTTP Basic authentication may be disabled without warning.

Considerations when Single Sign On is required

If your account is configured to require SSO for logins, API access through OAuth2 is only available when authenticating as the account owner. This restriction ensures that users who have been removed from your identity provider (IdP) aren't able to continue accessing your Resource Guru account with unexpired API tokens.

Getting started

We recommend using an OAuth2 library for the platform you're working with, rather than working from scratch. A fairly comprehensive list of libraries can be found here.

  1. Register an app at developers.resourceguruapp.com. Your app will be assigned a client_id and client_secret that will be used to identify your app when users authenticate with the API. You'll need to provide a redirect_uri where we'll send the verification code for authentication. Just use a fake URL like http://localhost/oauth if you haven't got one yet. Any Redirect URI given must be secure (HTTPS) unless it redirects to localhost.

  2. Configure your OAuth2 library to use the client_id, client_secret and redirect_uri for your app. You'll need to configure these URLs as well:

    • https://api.resourceguruapp.com/oauth/authorize to request authorization (must be requested with an HTTP GET request).
    • https://api.resourceguruapp.com/oauth/token to retrieve tokens (must be requested with an HTTP POST request).
  3. Authenticate with the API. We'll provide code samples using the intridea/oauth2 library in Ruby.

    Quick start using user's login credentials

    This method is only recommended for private apps, such as data imports and exports or internal business reporting. It's useful to get started quickly without all of the overhead of OAuth2 though, which makes it great for exploration. This should not be used for integrating 3rd party apps with Resource Guru as it requires knowing the user's private credentials.

    We support the OAuth2 password grant type. To authenticate, make an HTTP POST to /oauth/token with the following:

    {
      "grant_type"    : "password",
      "username"      : "user@example.com",
      "password"      : "secret",
      "client_id"     : "the_client_id",
      "client_secret" : "the_client_secret"
    }

    You'll receive the access token back in the response:

    {
      "access_token": "the_oauth_access_token",
      "refresh_token": "the_oauth_refresh_token",
      "token_type": "bearer",
      "expires_in": 604800
    }

    To use this with the OAuth2 Ruby library is easy:

    client = OAuth2::Client.new(client_id, client_secret, site: "https://api.resourceguruapp.com")
    token = client.password.get_token("user@example.com", "secret")
    token.get("/v1/example-corp/resources")

    The password grant method shown above is great for getting started quickly, but is impractical for apps that require users to authenticate with Resource Guru as you would have to store the user's Resource Guru login credentials.

    We support the standard auth code flow as well. Here is a code sample in Ruby of how to authenticate this way.

    require 'oauth2'
    
    client_id = ENV["CLIENT_ID"]
    client_secret = ENV["CLIENT_SECRET"]
    redirect_uri = ENV["REDIRECT_URI"]
    
    client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
    
    puts client.auth_code.authorize_url(redirect_uri: redirect_uri)

    Go to the URL provided to authorize with the API. This is the URL you'll direct users to to allow your app to access the API. When you've authorized with the API, the browser will be redirected to the redirect_uri you provided and the authorization code will be sent as a parameter in the URL. For example if your redirect_uri was https://localhost/oauth/callback, the user will be redirected to https://localhost/oauth/callback?code=<the code>

    Use this code to retrieve an access token and refresh token:

    code = "code sent to the redirect_uri in the previous step"
    access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
    access_token.get("/v1/example-corp/resources")

    Save the values returned as access_token.token, access_token.refresh_token and access_token.expires_at for later usage.

    To connect to the API with a known token:

    client_id = ENV["CLIENT_ID"]
    client_secret = ENV["CLIENT_SECRET"]
    redirect_uri = ENV["REDIRECT_URI"]
    oauth_token = ENV["OAUTH_TOKEN"]
    refresh_token = ENV["REFRESH_TOKEN"]
    expires_at = ENV["EXPIRY"]
    
    client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
    access_token = OAuth2::AccessToken.new(client, oauth_token, refresh_token: refresh_token, expires_at: expires_at)
    access_token.get("/v1/example-corp/resources")

    In the above example using the token expiry time stamp is optional, but the OAuth2 library will automatically handle refreshing tokens if it is provided.

  4. Tokens expire after 7 days and need to be refreshed. When authenticating, a refresh token and expiration timestamp is provided. Use the refresh token to retrieve a new access token. Most OAuth2 client libraries will handle this automatically.

    client_id = ENV["CLIENT_ID"]
    client_secret = ENV["CLIENT_SECRET"]
    redirect_uri = ENV["REDIRECT_URI"]
    oauth_token = ENV["OAUTH_TOKEN"]
    refresh_token = ENV["REFRESH_TOKEN"]
    expires_at = ENV["EXPIRY"]
    
    client = OAuth2::Client.new(client_id, client_secret, site: 'https://api.resourceguruapp.com')
    access_token = OAuth2::AccessToken.new(client, oauth_token, refresh_token: refresh_token, expires_at: expires_at)
    new_access_token = access_token.refresh
    new_access_token.get("/v1/example-corp/bookings")

    The old access token will be expired immediately and the new access token will have to be used from that point on. Make sure you save the new access token, refresh token and expiration timestamps when doing this.

Examples

Python 3

from urllib.parse import urlencode
import json
import requests

client_id     = 'APPLICATION_CLIENT_ID'
client_secret = 'APPLICATION_SECRET'
redirect_uri  = 'REDIRECT_URI'
authorize_url = "https://api.resourceguruapp.com/oauth/authorize?client_id=%(client_id)s&redirect_uri=%(redirect_uri)s&response_type=code" % locals()

# Visit the Auth URL -> authorize_url defined above
# Get code token after authorizing
returned_code = input("Enter the code from the authorization step: ")

parameters = {
  'client_id': client_id,
  'client_secret': client_secret,
  'code': returned_code,
  'grant_type': "authorization_code",
  'redirect_uri': redirect_uri
}

token_url = 'https://api.resourceguruapp.com/oauth/token'
token     = requests.post(token_url, urlencode(parameters)).json()
headers   = { "Authorization": "Bearer " + token['access_token'] }

resources = requests.get("https://api.resourceguruapp.com/v1/example-account-id/resources", headers=headers).json()

# Now let's play in an interactive console
import code;code.interact(local=dict(globals(),**locals()))

Bash

#!/bin/bash

client_id='APPLICATION_CLIENT_ID'
client_secret='APPLICATION_SECRET'
redirect_uri='REDIRECT_URI'
authorize_url="https://api.resourceguruapp.com/oauth/authorize?client_id=$client_id&redirect_uri=$redirect_uri&response_type=code"
token_url='https://api.resourceguruapp.com/oauth/token'

echo "Please follow the given link: $authorize_url"
echo "Please provide the given code, followed by [ENTER]:"

read code

token_data=`curl --data "grant_type=authorization_code" --data-urlencode "client_id=$client_id" --data-urlencode "client_secret=$client_secret" --data-urlencode "code=$code" --data-urlencode "redirect_uri=$redirect_uri" $token_url`
token=`echo $token_data | jsawk 'return this.access_token'`

resources_url="https://api.resourceguruapp.com/v1/example-account-id/resources"

echo `curl -H "Authorization: Bearer $token" $resources_url`

Ruby

require "oauth2"

client_id = "APPLICATION_CLIENT_ID"
client_secret = "APPLICATION_SECRET"
redirect_uri = "REDIRECT_URI"

client = OAuth2::Client.new(client_id, client_secret, { site: { url: 'https://api.resourceguruapp.com'}})
authorize_url = client.auth_code.authorize_url(redirect_uri: redirect_uri)

# Visit the Auth URL -> authorize_url defined above to get the code
puts "Enter the code from the authorization step"
code = gets.strip

access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)

access_token.get("/v1/example-account-id/resources")

# Now let's play in an interactive console
require "IRB"
IRB.start

Data types