API Basics
The main URL for all API calls
http://api.jirafe.com/v1
API Version
Every API call begins with API version. List of available API versions can be found at http://api.jirafe.com/versions
Format
Response format for all requests is JSON.
Response Status Codes
- 200 OK. For successful GET and PUT request.
- 201 CREATED. Successful POST.
- 400 BAD REQUEST. Check URL and input data.
- 401 UNAUTHORIZED. Action require authentication.
- 403 FORBIDDEN. Failed to authenticate.
- 404 NOT FOUND. Resource not found.
- 409 CONFLICT. For unsuccessful POST, PUT, or DELETE.
Error format
The error format is returned in json and is respecting the following pattern ("data" field may not be present for each error):
{
"error": {
"code": 400,
"message": "Invalid User resource provided.",
"data": [
"[email]() - Email cannot be blank"
]
}
}
Authentication
You must pass a token to each method that require anthentication. So you will need to append ?token=TOKEN_VALUE to each api call requiring authentication. A token is associated to each User.
Required fields
In the following documentation, required fields in POST and PUT request queries are in bold.
Sites resource
In order to get site information
As an API user
I need to be able to make calls to /v1/applications/APP_ID/sites resource
As an API user
I need to be able to make calls to /v1/applications/APP_ID/sites resource
Get orders sync status for a specific site (when there is no error)
GET
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID/orders/status?token=TOKEN
CODE: 200
{
"ok": 1,
"version": 0,
"errors": ""
}
Get orders sync status for a specific site (when there is an error)
GET
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID/orders/status?token=TOKEN
CODE: 200
{
"ok": 1,
"version": 3,
"errors": ""
}
Get orders sync status for a specific site (when there is an error)
GET
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID/orders/status?token=TOKEN
CODE: 200
{
"ok": 1,
"version": 5,
"errors": "An order synchronization error might have occurred, Jirafe has been notified and we will be in touch if we need more information from you"
}
Get orders sync status for a specific site (when there is an error)
GET
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID/orders/status?token=TOKEN
CODE: 200
{
"ok": 0,
"version": 2,
"errors": "An order synchronization error might have occurred, Jirafe has been notified and we will be in touch if we need more information from you"
}
Get orders sync status for a specific site (when there is an error)
GET
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID/orders/status?token=TOKEN
CODE: 200
{
"ok": 0,
"version": 4,
"errors": "An order synchronization error might have occurred, Jirafe has been notified and we will be in touch if we need more information from you"
}
Update site storeCartUrl by it's ID
PUT
http://api.jirafe.com
/v1/applications/APP_ID/sites/SITE_ID?token=TOKEN
| store_cart_url | = | http://test.com/cart |
|---|
CODE: 200
{
"site_id": SITE_ID,
"app_id": APP_ID,
"description": "Jirafe API",
"url": "http://api.jirafe.com",
"timezone": "Europe/Paris",
"currency": "EUR",
"external_id": "",
"store_api_url": null,
"store_cart_url": "http://test.com/cart"
}
Sync resource
Sync is a synchronization api call, which updates inserts or removes all given or missing users, sites.
If there was an user or site created before, it must be included in this call in order to update, maintain it. If it is not included and it exists
in jirafe database - it will be removed, otherwise if it does not exist - will be created.
Be careful with custom or manual sync API calls unless you are sure about the outcomes.
Sync call is mainly used in jirafe plugins for simple and effective data updates and is not recommended for manual use cases.
If there was an user or site created before, it must be included in this call in order to update, maintain it. If it is not included and it exists
in jirafe database - it will be removed, otherwise if it does not exist - will be created.
Be careful with custom or manual sync API calls unless you are sure about the outcomes.
Sync call is mainly used in jirafe plugins for simple and effective data updates and is not recommended for manual use cases.
Insertion of users and sites
Timezone should be one the IANA tz database (http://en.wikipedia.org/wiki/Tz_database). The list of valid timezones can be found here: http://api.jirafe.com/timezones.
POST
http://api.jirafe.com
/v1/applications/APP1_ID/resources?token=cloud_app_token
| users[0][email] | = | john_doe@example.com |
|---|---|---|
| users[0][first_name] | = | john |
| users[0][last_name] | = | doe |
| sites[0][external_id] | = | 23 |
| sites[0][description] | = | sample description |
| sites[0][url] | = | http://sample.com |
| sites[0][currency] | = | EUR |
| sites[0][timezone] | = | Europe/Paris |
| sites[0][store_api_url] | = | http://sample.com/sync |
| sites[0][store_cart_url] | = | http://sample.com/cart |
CODE: 200
{
"sites": [
{
"app_id": 1,
"currency": "EUR",
"description": "sample description",
"external_id": "23",
"site_id": 1,
"timezone": "Europe/Paris",
"store_api_url": "http://sample.com/sync",
"store_cart_url": "http://sample.com/cart",
"url": "http://sample.com"
}
],
"users": [
{
"user_id": USER3_ID,
"email": "john_doe@example.com",
"first_name": "john",
"last_name": "doe",
"mobile_phone": null,
"token": "TOKEN",
"username": null
}
]
}
Update few sites at once
You must provide the "site_id" in order to update a site during sync.
POST
http://api.jirafe.com
/v1/applications/APP1_ID/resources?token=cloud_app_token
| sites[0][site_id] | = | SITE1_ID |
|---|---|---|
| sites[0][description] | = | my site |
| sites[0][url] | = | https://site.com/now/secured |
| sites[1][site_id] | = | SITE2_ID |
| sites[1][description] | = | I change the description |
CODE: 200
{
"sites": [
{
"app_id": 1,
"currency": "EUR",
"description": "my site",
"external_id": "",
"site_id": 1,
"timezone": "Europe/Paris",
"store_api_url": null,
"store_cart_url": null,
"url": "https://site.com/now/secured"
},
{
"app_id": 1,
"currency": "EUR",
"description": "I change the description",
"external_id": "",
"site_id": 2,
"timezone": "America/New_York",
"store_api_url": null,
"store_cart_url": null,
"url": "http://other.com"
}
],
"users": []
}
Synchronize sites, users and update application data
If "opt_in" (1 - on, 0 - off) field is provided, all new users synchronized will receive an invitation email to register into "Jirafe cloud" and be able to pay for jirafe services which may be accessible for the platform used.
POST
http://api.jirafe.com
/v1/applications/APP1_ID/resources?token=cloud_app_token
| users[0][email] | = | john@jirafe.com |
|---|---|---|
| users[0][first_name] | = | john |
| sites[0][external_id] | = | 23 |
| sites[0][description] | = | Jirafe |
| sites[0][url] | = | http://jirafe.com |
| sites[0][currency] | = | EUR |
| sites[0][timezone] | = | Europe/Paris |
| sites[0][store_api_url] | = | http://jirafe.com |
| sites[0][store_cart_url] | = | http://jirafe.com/cart |
| opt_in | = | 1 |
| platform_type | = | magento |
| plugin_version | = | 1.1.3 |
| platform_version | = | 1.5.1.0 |
CODE: 200
{
"sites": [
{
"app_id": 1,
"currency": "EUR",
"description": "Jirafe",
"external_id": "23",
"site_id": 1,
"timezone": "Europe/Paris",
"store_api_url": "http://jirafe.com",
"store_cart_url": "http://jirafe.com/cart",
"url": "http://jirafe.com"
}
],
"users": [
{
"user_id": USER3_ID,
"email": "john@jirafe.com",
"first_name": "john",
"last_name": null,
"mobile_phone": null,
"token": "TOKEN",
"username": null
}
]
}
Application members resource
In order to manage application members
As an API user
I need to be able to make /applications/app_id:/members calls
As an API user
I need to be able to make /applications/app_id:/members calls
List members of an application
GET
http://api.jirafe.com
/v1/applications/APP_ID/members?token=secret_token
CODE: 200
[
{
"email": "georges.abitbol@jirafe.com",
"first_name": "Georges",
"last_name": "Abitbol",
"mobile_phone": null,
"token": "georges_app_token",
"user_id": USER1_ID,
"username": null
},
{
"email": "gedi@jirafe.com",
"first_name": "Gedi",
"last_name": "Knight",
"mobile_phone": null,
"token": "gedi_app_token",
"user_id": USER2_ID,
"username": null
}
]
Add a new member to the application
PUT
http://api.jirafe.com
/v1/applications/APP_ID/members/USER_ID?token=secret_token
CODE: 200
{
"token": "TOKEN3",
"app_id": APP_ID,
"user_id": USER_ID
}
Remove a member from the application
DELETE
http://api.jirafe.com
/v1/applications/APP_ID/members/USER_ID?token=secret_token
CODE: 204
Applications resource
In order to manage applications
As an API user
I need to be able to make /applications calls
As an API user
I need to be able to make /applications calls
Get application
GET
http://api.jirafe.com
/v1/applications/APP_ID?token=TOKEN
CODE: 200
{
"app_id": APP_ID,
"name": "my application"
}
Create new application
POST
http://api.jirafe.com
/v1/applications
| name | = | new app |
|---|
CODE: 200
{
"app_id": APP_ID,
"name": "new app",
"token": "TOKEN"
}
Update existing application
PUT
http://api.jirafe.com
/v1/applications/APP_ID?token=TOKEN
| name | = | new name |
|---|
CODE: 200
{
"app_id": APP_ID,
"name": "new name"
}