API introduction

The Bouquet API makes it easy to access resources in a simple and programmatic way using conventional HTTP requests. All production API requests are made to the Bouquet Server URL.

e.g. https://demo.openbouquet.io

All data is sent and received as JSON.

Some of our API endpoints require OAuth 2.0 credentials. Please see the Authentication & Authorization section to get started.

Request and response

Requests are made of three components:

  • Base URL: https://demo.openbouquet.io
  • API version: release/v4.2
  • Resource path: projects
To construct a proper request, you need to format the URL as follows:

https://{base_url}/{api_version}/{resource}

Example: https://demo.openbouquet.io/release/v4.2/projects

% curl -H 'Content-Type: application/json' https://demo.openbouquet.io/release/v4.2/projects?access_token={tokenId}

The following code is an example request to retrieve detailed information about a project.

Authentication & Authorization

You authenticate to the API by requesting a token. You can create a token on your API domain e.g. demo.openbouquet.io domain with a POST request on the /rs/auth-token HTTP resource.

Basic Authentication process:

  • Query via POST request the /rs/auth-token resource

  • Supply an "access_token" parameter followed by the token you get previously, e.g. 3698537-7190-4a6e-9127-3e84057f47f1

curl -X GET -H "Content-Type: application/json" https://demo.openbouquet.io/{api_version}/{resources}?access_token={tokenId}

All API calls must be performed by a registered API application (also named "client") on behalf of a registered user. Both (the application and the user) are verified for each API call by passing an access token along with each request.

Access tokens are unique and are obtained using an OAuth method.

There are two ways to use OAuth:

Server-side:

Referred to "Authorization Code Grant" in the OAuth 2.0 Specification. The server-side method should be used whenever you need to call the API from your web application server.

User authentication and app authorization are handled at the same time by redirecting the user to the OAuth login Dialog.

In the OAuth login Dialog the user must pass in an application key (the client_id parameter) and an URL to redirect the user once the app authorization is completed (the redirect_uri parameter).

The redirect_uri must be within the same domain as the site URL you specify when you create your Client Id (or application key):

  • client_id : Your Client Id (or application key).
  • redirect_uri : The URL on your site that will handle the result of authorization.
  • response_type : The kind of response required (for the server-side method it should be "code").
https://demo.openbouquet.io/{api_version}/oauth?client_id=[client_id]&redirect_uri=[redirect_uri]&response_type=code

Once the user authenticated, the OAuth dialog will redirect (via HTTP 302) the user’s browser to the URL passed in the redirect_uri parameter with an authorization code.

http://[redirect_uri]?code=[code]
With this code you can proceed to the next step, app authentication, to gain the access token you need to make API calls.

In order to authenticate your app, you must pass the authorization code and your app secret to the OAuth token access endpoint

https://demo.openbouquet.io/{api_version}/rs/token

The app secret is generated when you register your application and should not be shared with anyone or embedded in any code that you will distribute.

If your app is successfully authenticated and the authorization code from the user is valid, the authorization server will return an access token object.

Request :

curl -X POST -H "Content-Type: application/json" https://demo.openbouquet.io/{api_version}/token?client_id=[client_id]&client_secret=[client_secret]&code=[code]

The token endpoint will respond with a JSON object that describes the token or an error.

Client-side

Referred to as "Implicit Grant" in the OAuth 2.0 Specification. The client-side method should be used when you make an API call from a client, such as JavaScript running in a web browser or from a native mobile or desktop application.

This method is aimed at supporting Javascript based applications The client-side method also uses the OAuth Dialog for user authentication and app authorization.

The only difference is that you must specify the response_type parameter with a value of "token".

https://demo.openbouquet.io/{api_version}/oauth?client_id=[client_id]&redirect_uri=[redirect_uri]&response_type=token
Once the user is authenticated and authorized, your application, the browser will be redirected to the redirect_uri but rather than being passed a authorization code (via the code parameter) as in the server-side method, the access token itself is passed.
https://[redirect_uri]?access_token=[access_token]
Because the access token is passed in an URI fragment, only client-side code (such as JavaScript executing in the browser or desktop code hosting a web control) can retrieve the token.

However, tokens received on the fragment MUST be explicitly validated.
Failure to verify tokens acquired this way makes your application more vulnerable to the "confused deputy" problem.

You can validate a token by making a web service request to a 'tokeninfo' endpoint and performing a string match on the results of that web service request :

curl -X GET -H "Content-Type: application/json" https://demo.openbouquet.io/{api_version}/tokeninfo?access_token=[access_token]
The tokeninfo endpoint will respond with a JSON object that describes the token or an error.

To verify a token, ensure the 'client_id' field in the response exactly matches yours.

This is the mitigation for the confused deputy issue, and it is absolutely vital to perform this step.

Client and Server side

Both methods involve three steps:

  • User authentication: Checks the user identity.
  • App authorization: Ensures the user knows that they are allowing your application to access their data.
  • App authentication: Ensures the user is giving their information to your application and not another one. 
 
Errors

Bouquet API uses conventional HTTP response codes to indicate success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter is missing), and codes in the 5xx range indicate an error with Bouquet servers.

HTTP Status Code Summary
  • 200 OK - Everything worked as expected.

  • 201 Created - API returns a 201 after a successful POST where a resource was created.

  • 204 Deleted - API returns a 204 after a successful DELETE where a resource was deleted.

  • 400 Bad Request - Malformed request, often due to a missing required parameter.

  • 401 Unauthorized - Unauthorized the request requires user authentication (not logged in).

  • 402 Request Failed - Parameters were valid but request failed.

  • 403 Forbidden - Insufficient privileges to access requested resource.

  • 404 Not Found - The requested resources doesn't exist.

  • 409 Conflict - A conflict needs to be resolved before the request can be made.

  • 50x Server errors - something went wrong on api domain's end.

Input and output data must be valid JSON with appropriate Content-Type header set.

Example
  • Response 401 (application/json)

        {
            "code": 401,
            "type": "InvalidTokenAPIException",
            "error": "Auth failed : invalid access_token",
            "suppressed": []
        }
    
  • Response 404 (application/json)

        {
            "code": 404,
            "type": "ObjectNotFoundAPIException",
            "error": "User not found for given login / password",
            "suppressed": []
        }

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.