Using the API¶

Supported HTTP methods¶

When building a REST API, the challenge is to represent the data and the action upon the data as a path to a resource that can be created, retrieved, updated, or deleted. The HTTP methods POST, GET, PUT, and DELETE correspond to the actions that are applied to resources.

Base URL¶

The base url for all requests made to Usergrid depends on where you have Usergrid installed. If you are using Apigee’s trial Usergrid service, the base URL is https://api.usergrid.com.

Request construction¶

Usergrid interprets the URL resource path as a list of names, UUIDs, or queries. The basic path format is:

https://api.usergrid.com/<org-uuid|org-name>/<app-uuid|app-name>/<collection-name>/<entity-uuid|entity-name>

Note: You cannot mix UUIDs and names in the URL resource path. For example, the following is incorrect:

https://api.usergrid.com/your-org/62de5d97-d28c-11e1-8d5c-12313b01d5c1/users/john.doe

Accessing collections¶

To access all entities in a collection, specify the path as follows:

/users

Such a request retrieves the first 10 entities in the collection /users sorted by their entity UUID.

Accessing entities¶

To access an entity in a collection, specify the path as follows:

/<collection>/<uuid|name>

where <collection> is the collection name, and is the entity’s uuid or name.

To access a user in the users collection, specify the path as follows:

/users/<uuid|username|email_address>

where <uuid|username|email_address> is the user’s uuid, username, or email address.

For example, the following request retrieves the entity named dino from the dogs collection:

/dogs/dino

Issuing queries¶

You can issue a query in an API request that retrieves items from a collection. Here is the typical format for queries:

/<collection>?ql=<query>

where is a query in the query language.

For example, this request retrieves users whose Facebook first name is john:

/users?ql=select * where facebook.first_name ='john'

For further information about queries, see Querying your Data

Authentication (OAuth)¶

Usergrid implements the OAuth 2.0 standard for authenticating users, clients and API requests.

Generally, you will generate a token for every user of your app by providing the user’s username and password. The token can then be sent with all API requests to ensure each user is only able to access and modify the resources you have granted them rights to.

Note that by default access tokens are not needed to make requests to the default sandbox application in an organization.

For more information on generating and using access tokens, see Authenticating users and application clients and Authenticating API requests.

Response format¶

All API methods return a response object that typically contains an array of entities:

{
  "entities" : [
    ...
  ]
}

Not everything can be included inside the entity, and some of the data that gets associated with specific entities isn’t part of their persistent representation. This is metadata, and it can be part of the response as well as associated with a specific entity. Metadata is just an arbitrary key/value JSON structure.

For example:

{
  "entities" : {
    {
      "name" : "ed",
      "metadata" : {
        "collections" : ["activities", "groups", "followers"]
      }
    }
  },
  "metadata" : {
    "foo" : ["bar", "baz"]
  }
}

For example, here is the response to a basic GET for a user entity:

{
  "action" : "get",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/users",
  "uri" : "https://api.usergrid.com/your-org/your-app/users",
  "entities" : [ {
    "uuid" : "503f17da-ec39-11e3-a0dd-a554b7fbd57a",
    "type" : "user",
    "created" : 1401921665485,
    "modified" : 1401921665485,
    "username" : "someUser",
    "email" : "someUser@yourdomain.com",
    "activated" : true,
    "picture" : "http://www.gravatar.com/avatar/dc5d478e9c029853fbd025bed0dc51f8",
    "metadata" : {
      "path" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a",
      "sets" : {
        "rolenames" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles",
        "permissions" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/permissions"
      },
      "collections" : {
        "activities" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/activities",
        "devices" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/devices",
        "feed" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/feed",
        "groups" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/groups",
        "roles" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/roles",
        "following" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/following",
        "followers" : "/users/503f17da-ec39-11e3-a0dd-a554b7fbd57a/followers"
      }
    }
  } ],
  "timestamp" : 1401921673597,
  "duration" : 12,
  "organization" : "your-org",
  "applicationName" : "your-app"
}

SDKs¶

To make the integration of Usergrid features into your application code quicker and easier, Usegrid offers SDKs in a variety of languages. The SDKs contain language-specific methods that allow you to issue API requests from your application code in your preferred language. SDKs are available for the following languages:

• iOS
• Android
• JavaScript/HTML5
• Node.js
• Ruby
• .NET

For more information, see SDKs.