How can I use the Backupify Google Apps API?

Follow

The Google Apps API makes it easy for Enterprise customers to manage their SaaS Protection/Backupify account. Currently, the API facilitates user management within your SaaS Protection/Backupify account.

This documentation covers our RESTful API.

Getting Started

If you are an Enterprise or Enterprise+ customer, you'll gain access to our API through two unique keys: Client ID and Client Secret.  If you would like to upgrade to an Enterprise-level package to gain access to the Backupify API or if you have any questions, contact Datto support.

By default no keys are created for your account. To generate your keys:

  1. Sign in to SaaS Protection/Backupify as the account owner.
  2. Access Account Settings.
  3. Choose the API Tokens tab and click Generate API Keys
 
NOTE: The API Tokens tab is also where you can regenerate or delete your keys at any time. Regenerating or deleting keys renders all earlier keys invalid and you will have to re-enter the newest keys before accessing the API again.

The API keys authenticate the retrieval of your OAuth2 tokens and allow access to the full Backupify Google Apps API as well as every domain and subdomain within your account. These keys are unique to you and you should keep them secret.

Once you have retrieved an access token, you should include it in the request headers for every API request under the Access-Token header. All requests must be made via HTTPS/SSL for security.

Using Tokens

Generating Access Tokens

Using your client_id and client_secret, you can make a request for an access token from https://api.backupify.com/oauth/token. For example:

curl -XPOST https://api.backupify.com/oauth/token --data-urlencode 'client_id={client_id}' --data-urlencode 'client_secret={client_secret}' -d 'grant_type=client_credentials&scope=write'

Example response:

{

    'access_token':
    `hhZkpodIrH1mRV8hmhSMxH9oOKRZH5xDnLYa8hL9YJrVFRfXwVuypVkgZVOiU+zba      Io30yCeQXG7jLRvYGZURg=='

     'token_type':

     'bearer' 'expires_in': 899

}

where "expires_in" is listed in seconds.

If any credentials were malformed or are insufficient, you will receive an error.

Example Error:

{

     'error': 'invalid_client'

     'error_description': 'The client identifier provided in invalid, the client failed to
     authenticate, the client did not include its credentials, provided multiple client
     credentials, or used unsupported credentials type.'

}

Authentication

Every request must be accompanied by an access token in the Authorization header as follows:

curl -H 'Authorization: {AccessToken}' https://api.backupify.com/gapps/{APIVersion}/{Endpoint}

An invalid access token will result in a 401 Unauthorized.

Errors: Responses to client errors that require additional information to be sent will package errors in this form:

{

     message: 'Some attributes were invalid.'

     errors: [

     {

          field: 'first_name'

          message: 'Can't have special characters.'

     } ]

}

If a server error is encountered when processing a request, the server will issue a 500.

If the Google Apps API is down for maintenance, a request will result in a 503.

User Management API

List Users

List Users retrieves a paginated list of users for the given domain. API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users

Allowed Method: GET

Parameters

PARAMETER TYPE REQUIRED? DESCRIPTION
status string No The type of users you would like to retrieve, by status. Can be 'archived' or 'active'. The default is 'all'.
page integer No The number of pages of users to skip.
per_page integer No The number of users to return. The maximum is 100. The default is 25.

Example response

{

     "next_page": 'nextPageLink',

     "total_entries": 25,

     "users": [

     {

          "name": 'user.full_name'

          "email": 'user.email',

          "status": 'user.status',

          "org_unit": 'user.org_unit_name'

          "service_status":

          {

               "service_name":

               {

                    "link": 'service.link',

                    "service_id": 'service.id',

                    "status": 'service.status'

               }

          }

     } ]

}

 

Attributes

NAME TYPE DESCRIPTION
next_page string The url to fetch the next page of users.
total_entries integer The total number of users.
users array An array of user objects.

 

Error Status

HTTP Status Code

Reason

200

Success

 

Example Request(s) 

curl https://api.backupify.com/gapps/v1/domains/backupify/users curl https://api.backupify.com/gapps/v1/domains/backupify/users?page=2&per_page=50

Get a User

Get a User retrieves a user.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users/{UserEmail}

Allowed Method: GET

Example Response

{

     "email": 'user.email',

     "name": 'user.full_name',

     "status": 'user.status',

     "org_unit": 'user.org_unit_name',

     "service_status":

     {

          "service_name":

          {

               "link": 'service.link',

               "service_id": 'service.id',

               "status": 'service.status'

          }

     }

}

 

Attributes

NAME

TYPE

DESCRIPTION

email

string

User's email.

name

string

User's full name.

status

string

Status indicating whether user is active or archived.

org_unit

string

User's organizational unit's name.

service_status

hash

Contains a summary of service statuses keyed by name.

service_name

string

The human readable name of the service i.e., Google Mail Service, Google Docs Service, etc.

link

string

The url to retrieve detailed status information about a single service.

service_id

integer

The unique ID for the service.

status

string

Either 'partial' or 'complete'. If we have successfully backed up all scheduled files then this field will read 'complete'. If we have missed a file and need to retry in the future this field will read 'partial'.

 

Error Status 

HTTP Status Code

Reason

200

Success

404

No user with that email was found within the application or within the current domain.

 

Example Request(s)

curl https://api.backupify.com/gapps/v1/domains/backupify/users/bob.smith@backupify.com

Add a User

Add a User adds a user to the given domain in SaaS Protection/Backupify. API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users -d 'user[email]={UserEmail}'

Allowed Method: POST

Data 

Data Attribute

Description

user[email]

The user's email.

 

Example Response 

No Content.

 

Status Codes 

HTTP Status Code

Reason

200

The user already exists in the application.

201

The user was added to the application.

400

The user[email] parameter was not provided, or was incorrectly formatted.

402

The user was not added due to a billing issue. Please contact Datto for more information.

404

No user with that email was found within the domain or you do not have access to the specified domain.

 

Example Request(s) 

curl -X POST https://api.backupify.com/gapps/v1/domains/backupify/users -d 'user[email]=bob.smith@backupify.com'

Delete a User

Delete a User removes the user from the given domain in SaaS Protection/Backupify. WARNING: This is not reversible, and the deleted user and their data will no longer be accessible within Backupify.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users/{UserEmail}

Allowed Method: DELETE

Example Response

No content

Status codes

HTTP Status Code Reason
200 The user was removed successfully.
404 No user with that email was found within the domain.

 

Example Request(s)

curl -X DELETE https://api.backupify.com/gapps/v1/domains/backupify/users/bob.smith@backupify.com

 

Get a Service

Get a Service retrieves detailed status information for a service.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}

Allowed Method: GET

Example Response 

{

     "id": 42,

     "service_type": 'Google Mail Service',

     "user_email": "bob.smith@backupify.com",

     "last_attempted_backup": '2014-02-19T16:50:48Z',

     "last_successful_backup": '2014-02-19T16:50:48Z',

     "status": 'complete'

     "backup_in_progress": false,

     "storage": '38.7 MB'

}

Attributes 

Name Type Description
backup_in_progress boolean Indicates whether a backup is currenly in progress for this service.
id integer The unique ID for the service.
last_attempted_backup string The last time a backup was attempted in ISO-8601 format.
last_successful_backup string The last time a backup completed successfully in ISO-8601 format.
service_type string The human readable name for this service.
status string Either 'partial' or 'complete'. If we have successfully backed up all scheduled files then this field will read 'complete'. If we have missed a file and need to retry in the future this field will read 'partial'.
storage string How much data we have backed up for this service.
user_email string Email of the user the queried service belongs to

 

Error status 

HTTP Status Code Reason
200 Success
404 No service with that ID was found within the current domain.

 

Example Request(s) 

curl https://api.backupify.com/gapps/v1/domains/backupify/services/42

Export Management API

List Exports

List Exports retrieves a list of all exports created in the past 30 days for a given service.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports

Allowed Method: GET

Example Response

{

     "total_entries": 1,

     "exports": [

     {

          "id": 1,

          "service_id": 19,

          "created_at": "2014-03-10T18:41:07Z",

          "started_at": "2014-03-10T18:41:08Z",

          "ended_at": null,

          "state": "working",

          "result_email_destination": "admin@backupify.com", "archive_url": null

     } ]

}

Attributes 

Name Type Description
total_entries integer The total number of exports.
exports array An array of export objects.

 

Error Status

HTTP Status Code Reason
200 Success
404 No service with that ID was found within the current domain.

 

Example Request(s) 

curl https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports

Get Export

Get Export retrieves information about a given export, assuming it was created in the past 30 days.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports/{ExportID}

Allowed Method: GET

Example Response

{

     "id": 1,

     "service_id": 19,

     "created_at": "2014-03-10T18:41:07Z",

     "started_at": "2014-03-10T18:41:08Z",

     "ended_at": null,

     "state": "working",

     "result_email_destination": "admin@backupify.com",

     "archive_url": null

}

Attributes 

Name Type Description
id integer The ID of the export.
service_id integer The ID of the service the export belongs to.
created_at string The time that the export was created at, in ISO-8601 format.
started_at string The time that work on the export began, in ISO-8601 format. Null if work has not yet begun.
ended_at string The time that work on the export was completed, in ISO-8601 format. Null if work has not yet completed.
state string The state of the export; queued, working, successful, failed, or canceled.
result_email_destination string The email address to notify when the export has been completed.
archive_url string Where the export can be downloaded from. Null until the export is completed.

 

Error Status 

HTTP Status Code Reason
200 Success
404 No service or export with the given IDs was found within the current domain, or the export with that ID was created over 30 days ago.

 

Example Request(s) 

curl https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports/21

Start Export

Start Export starts an export for a given service.

API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports

Allowed Method: POST

Example Response

{

     "id": 5,

     "state": "queued"

}

Attributes

Name Type Description
id integer The ID of the export that has been created.
state string The state of the export; queued, working, successful, failed, or canceled.

 

Error Status 

HTTP Status Code Reason
200 Your request was successful, but an export for this service is already in progress.
201 An export was created.
404 No service with the given ID was found within the current domain.
500 The export failed to be created or enqueued in our system.

Example Request(s)

curl -X POST https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports

To contact support, please click here to submit a Support Request, or give us a call at (800) 518-7449 (USA) or +1 (475) 288-1818 (worldwide).


Was this article helpful?

0 out of 0 found this helpful

You must sign in before voting on this article.

Want to talk about it? Head on over to our Community Forum!