nanoHUB.org - nanoHUB.org

Home › Developer Portal › API › Documentation

Documentation

API: Home

Overview

Please note that you must register a developer application and authenticate with OAuth when making requests. Before doing so, be sure to read our Terms & Guidelines to learn how the API may be used.

Schema

All API access is over HTTPS, and accessed from the https://nanohub.org/api.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Errors

Below is an example of a standard error message returned from the API.

The HTTP response status in this example below would be 422 Validation Failed. It is included in the error response body since some clients have difficulty pulling the exact status message, vs the generic message.

{
	"code"    : 422,
	"message" : "Validation Failed",
	"errors"  : [	
		{
			"field"   : "cn",
			"message" : "Group cn cannot be empty."
		},
		{
			"field"   : "cn",
			"message" : "Invalid group ID. You may be using characters that are not allowed."
		}
	]
}

HTTP Verbs

Where possible, the API strives to use appropriate HTTP verbs for each action.

Verb	Description
GET	Used for retrieving resources, either a list or single resource
POST	Used for creating resources.
PUT	Used for updating resources, or performing custom actions
DELETE	Used for deleting resources.

Versioning

All endpoints through the API are versioned. You can supply the version in the request three different ways

In the URL:
```
/v1.3/groups
```
Query string parameter:
```
/groups?version=1.3
```
or
```
/groups?v=1.3
```
Custom Accept Header:
```
application/vnd.nanohub.v1.3
```

Rate Limiting

You can make up to 60 requests per minute, with a hard limit of 10,000 per day. For requests using OAuth, the rate limit is for each application and user combination. For unauthenticated requests, the rate limit is for the requesting IP address.

You can check the returned HTTP headers of any API request to see your current per minute rate limit status:

GET /groups/12345

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1392321600

The headers tell you everything you need to know about your current rate limit status:

Header	Description
X-RateLimit-Limit	The maximum number of requests that the consumer is permitted to make per minute.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

Once you go over the rate limit you will receive an error response:

HTTP/1.1 429 Too Many Requests
Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1392321600

{
	"code"    : 429,
	"message" : "Too Many Requests",
	"errors"  : []
}

** If you are exceeding your rate limit, you can likely fix the issue by caching API responses. If you’re caching and still exceeding your rate limit, please contact us to request a higher rate limit for your application.

JSON-P

You can send a callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

GET /groups/?callback=FooBar

FooBar([
	{
		"gidNumber":   "1234",
		"cn":          "testgroup",
		"description": "Test Group",
		"created":     "2015-01-29T19:58:07Z",
		"created_by":  "1000"
	},
	...
]);

You can write a JavaScript handler to process the callback like this:

function FooBar(groupsData)
{
	console.log(groupsData)
}

Expanding Objects

You can send an expand parameter to any GET call to have results expanded into full objects. This can be extremely useful and avoid having to make multiple requests.

GET /groups/12345?expand=created_by

{
	"gidNumber"   : "12345",
	"description" : "Test Group",
	"public_desc" : "Test Group Description",
	"logo"        : "/core/components/com_groups/site/assets/img/group_default_logo.png",
	"created"     : "2015-01-29T19:58:07Z",
	"created_by"  : {
		"uidNumber"    : "1000",
		"name"         : "John Doe",
		"organization" : "Hubzero",
		"url"          : "https://hubzero.org",
		"phone"        : "123-123-1234",
		"bio"          : "Donec ullamcorper nulla non metus auctor fringilla. Donec sed odio dui. Maecenas faucibus mollis interdum."
	}
}

Authentication (OAuth2)

OAuth2 is a protocol that lets external applications request authorization to private details in a user’s account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.

All developers need to register a developer application before getting started. A registered OAuth application is assigned a unique client ID and client secret. The client secret should not be shared.

Note, there are a number of different grant types you can use to authenticate a user via OAuth. Please read each type below to determine which type works best for your application.

Web Application Flow

This grant type is used for a typical web application, usually called "3 legged OAuth" The user is on your application and you send them to an authorization url (on this site) which asks them authorize the application to access the users data on their behalf.

1. Redirect to Authorization URL

GET /developer/oauth/authorize

Parameters

Name	Type	Description
client_id	string	Required. The client ID you received from your application when you registered your application.
redirect_uri	string	Required. The URL in your application where users will be sent after authorization. Must be one of the URLs you entered when registering your application.
state	string	Required. An unguessable random string. It is used to protect against cross-site request forgery attacks.
response_type	string	Required. At this time the only available option is "code"

2. HUB redirects back to your site

If the user accepts your request, the HUB will redirect back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

Exchange this for an access token:

POST /developer/oauth/token

Parameters

Name	Type	Description
client_id	string	Required. The client ID you received from your application when you registered your application.
redirect_uri	string	Required. Must be the URL you gave in Step 1.
grant_type	string	Required. Exchanging an authorization code for an access token, you must use the grant type "authorization_code".
code	string	Required. The code you received as a response to Step 1.

Response

The response will be returned as JSON and takes the following form:

{
	"access_token": "ac1cb855725c2eb8d5a3b29e70842fc3b5017293",
	"expires_in": 14400,
	"token_type": "Bearer",
	"scope": null,
	"refresh_token": "57c96d8372f7281572cb8063f0c9ad561ba8e903"
}

User Credentials Flow

This grant type is usually only used with trusted clients, just as a desktop or mobile application. In this grant type the users must enter their username and password which is sent and exchanged for an access token.

Request an access token

POST /developer/oauth/token

Parameters

Name	Type	Description
client_id	string	Required. The client ID you received from your application when you registered your application.
client_secret	string	Required. The client Secret you received from your application when you registered your application.
grant_type	string	Required. "password"
username	string	Required. The user's username.
password	string	Required. The user's password.

Response

The response will be returned as JSON and takes the following form:

{
	"access_token": "ac1cb855725c2eb8d5a3b29e70842fc3b5017293",
	"expires_in": 14400,
	"token_type": "Bearer",
	"scope": null,
	"refresh_token": "57c96d8372f7281572cb8063f0c9ad561ba8e903"
}

Refresh Token Flow

Refresh tokens are used to extend the length of an applications granted access token. Since each access token has a limited lifetime (couple hours), refresh tokens are issued with each access token request to extend their lifetime. Using a refresh token, allows you to "refresh" the access token after it has expired to get a new access token.

Although refresh tokens last much long (couple days, weeks, etc) they do expire eventually, so a user who hasnt actively used your application for longer then that period will be forced to login anyways.

Request an access token

POST /developer/oauth/token

Parameters

Name	Type	Description
client_id	string	Required. The client ID you received from your application when you registered your application.
client_secret	string	Required. The client Secret you received from your application when you registered your application.
grant_type	string	Required. "refresh_token"
refresh_token	string	Required. The refresh token you stored upon getting your original access token.

Response

The response will be returned as JSON and takes the following form:

{
	"access_token": "ac1cb855725c2eb8d5a3b29e70842fc3b5017293",
	"expires_in": 14400,
	"token_type": "Bearer",
	"scope": null,
	"refresh_token": "57c96d8372f7281572cb8063f0c9ad561ba8e903"
}

Session Token Flow

This grant type is used for internal HUB use only. It allows a web developer to create a client side application that communicates to the api via AJAX. This grant type will only work for a user with an active session (logged in user) from within the HUB in a component, module, plugin or template.

Request an access token

POST /developer/oauth/token

Parameters

Name	Type	Description
grant_type	string	Required. "session"

Response

The response will be returned as JSON and takes the following form:

{
	"access_token": "ac1cb855725c2eb8d5a3b29e70842fc3b5017293",
	"expires_in": 14400,
	"token_type": "Bearer",
	"scope": null
}

Tool Session Token Flow

This grant type is used for internal HUB use only. It allows for a tool session container to access the API. This grant type will only work from within an active tool container.

Request an access token

POST /developer/oauth/token

Parameters

Name	Type	Description
grant_type	string	Required. "tool"
sessionnum	string	Required. The Session ID number. This can typically be found in the resources file in the session data folder. This can be send as POST or HEADER parameter.
sessiontoken	string	Required. The Session Token. This can typically be found in the resources file in the session data folder. This can be send as POST or HEADER parameter.

Response

The response will be returned as JSON and takes the following form:

{
	"access_token": "ac1cb855725c2eb8d5a3b29e70842fc3b5017293",
	"expires_in": 14400,
	"token_type": "Bearer",
	"scope": null
}

Authenticating

The API uses OAuth2 to authenticate incoming requests. After obtaining your access token you must supply it with each request in the authorization header:

"Authorization: Bearer {ACCESS_TOKEN}"