Quire Tutorial - Open API

I - What is API?

Quire REST API provides a broad set of operations and resources that:

• Consistently do repetitive or tedious tasks
• Chain a process together for your team’s process and workflows
  • Pull information from other locations such as emails and Evernote into Quire.
  • Push information from Quire to other locations such as email and Zapier.

Want to share your thoughts on how Quire API works for you? Tell us how you feel about using our API and what we can do to make it better.

REST is a web-service protocol for rapid development by using HTTP and JSON technology.

II - Register an App with Quire API

1. Go to Developer app console then click Create new app button.

2. Give your app a cool name

Your app deserves a cool name that lives up to its wide broad of great features.

All of the app users will see this name in public, so think carefully!

3. Choose the Quire Organization that your app belongs to

You can choose an organization in Quire that your app belongs to.

If one day you decide to leave the organization, you will lose the authority to manage the app.

4. Redirect URL

When users grant your app authorization request, users will be directed to the configured URL that you’ve set.

5. Choose permission scopes

You can set permission on what your app can do with Quire. There are several options for you to choose from.

Note: If none of the options is selected, the app can only read user’s data.

6. Development Client ID and Client Secret

The Client ID and Client secret will be automatically generated as you create an app.

The Client ID is a unique ID to identify your app.

You should keep your client secret safe, which means you should never share your client secret with anyone. If you choose to regenerate the client secret, the old one will immediately become invalid.

7. Update your App

If your app hasn’t been published to Quire App Directory, it will remain as unpublished status. You can still use the configured shareable link in the Developer App Console Distribution to share the app with other users for testing or integration.

When you make changes to the app, you can use the shareable link to access the development copy as well. Working on your development copy will not affect your live App Directory app. When your updated app is ready to be published and replaced the old version on Quire App Directory, your published app will have a different Client ID to the unpublished one.

There are two sets of Client ID and Client Secret.

• Development set — should be used during developing and testing internally of the app.
• Production set — should be used once your app is ready and published on Quire App Directory.

III - Fulfill authorization request

1. Authorization code

When user grants the authorization request for your app, the user will be redirected to the configured URL that you’ve set when you created the app.

The authorization endpoint should look like this:

https://quire.io/oauth?client_id=your-client-ID&redirect_uri=your-redirect-uri

The authorization endpoint lets users grant your app access to the requested scope. After your app is granted, you can have an authorization code to exchange access token for access Quire API. The redirect_uri is optional. If not being specified, we will automatically use the one that is previously detected in the app. If specified, the redirect URL must start with the prefix of the one that was previously detected in the app.

2. Retrieve access token

To retrieve the access token, you have to post a request to https://quire.io/oauth/token with the following data:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=Your_code_from_previous_step&client_id=Your_app_client_id&client_secret=Your_app_client_secret" \
  https://quire.io/oauth/token

Then, the access token will be returned in the response's body.

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 2592000,
  "refresh_token": "REFRESH_TOKEN"
}

The token should be kept carefully and permanently since you need it to access every Quire API.

3. Token expiration

A refresh token might stop working for one of these reasons:

• The user has revoked your app's access.
• The refresh token has not been used for 6 months.

IV - How to use access token to access Quire API

After you exchange the access token, your app can make requests to Quire API on behalf of the authorized users.

curl -H 'Authorization: Bearer {access_token}' \
https://quire.io/api/user/id/me

{
  "email": "[email protected]",
  "website": "https://coolwebsites.com",
  "id": "My_ID",
  "description": "This is *cool*!",
  "url": "https://quire.io/u/My_ID",
  "nameText": "My Name",
  "nameHtml": "My Name",
  "descriptionText": "This is cool!",
  "descriptionHtml": "This is <i>cool</i>!",
  "image": "https://quire.s3.amazonaws.com/oid/image.jpg",
  "iconColor": "37",
  "name": "My Name",
  "oid": "Dyh2YkFcu9uLgLFIeN1kB4Ld"
}

V - Publish your app

By default, your app will be set as Private. You can change the app distribution to Public so that other Quire users can install your app to their workspace as well.

If your app is made available on Quire App Directory and you want to delete the app, you should communicate with your users first before depreciating the app.

For more details about the publication process, please visit our Developer Documentation.