The production version of your service API must be served over HTTPS.

Transcription

1 This document specifies how to implement an API for your service according to the IFTTT Service Protocol. It is recommended that you treat this document as a reference and follow the workflow outlined in our overview. General API requirements S The production version of your service API must be served over S. API URL prefix Designate an API URL prefix for all of your API endpoints in your service configuration. Examples Endpoint paths Endpoints are scoped to the current version of the IFTTT Service Protocol by appending your API URL prefix with /ifttt/v1 for all requests. Examples {{api_url_prefix}}/ifttt/v1/triggers/any_new_photo {{api_url_prefix}}/ifttt/v1/actions/post_photo Headers Use UTF-8 as the response encoding and support -level compression. Requests from IFTTT to your service API have the following headers: Headers

2 Content-Type: application/json status codes Use the following set of response status codes: status Description 200 The request was a success. There was something wrong with incoming data from IFTTT. Provide 400 an error response body to clarify what went wrong. 401 IFTTT sent an OAuth2 access token that isn t valid. 404 IFTTT is trying to reach a URL that doesn t exist. 500 There was an error in your application logic. Your service is not available at the moment, but IFTTT should try 503 again later. Response body format Provide response bodies as JSON objects. Success responses have a toplevel wrapper object called data. Raw body on success { "data": { // The value of `data` varies, but is typically // either an object or array... } } Error responses have a top-level errors array. Each element of errors is an object with a message property whose value is a user-friendly error message. Raw body on error

3 { "errors": [ { "message": "Something went wrong!" } ] } Service connection If your service requires user authentication, users must connect your service before they can use its triggers or actions. Service connection has two steps: 1. Authentication flow. This step authorizes IFTTT to make requests to your service API on behalf of the user. 2. Fetching and storing basic user information from your service API. Authentication flow IFTTT s protocol supports OAuth2 authentication, including support for refresh tokens if so desired. Your service API should use access tokens for authentication and as a source of identity. A single access token should correspond to a single user account or resource owner on your service. If refresh tokens are used, they must be non-expiring. If refresh tokens are not used, access tokens must be non-expiring. IFTTT client credentials When configuring your service, provide IFTTT with a client ID and client secret for authentication-related requests. IFTTT authorization Request

4 To begin authentication, IFTTT redirects the user to your OAuth2 Authorization URL, specified in the Service Authentication settings, and makes the following request: Request Method GET URL Your OAuth2 Authorization URL Parameters client_id IFTTT s client ID for your service as set in your service configuration. response_type code scope ifttt The ifttt scope should provide access to resources for every trigger and action in your service. This way, users will not need to repeat the authentication flow to use all of your triggers and actions. You may override this parameter by specifying your own scope in the OAuth2 Authorization URL specified in the Service Authentication settings. state An anti-forgery token provided by IFTTT. redirect_uri channel_slug is a string used to represent your service in URLs. You can set in your service configuration.

5 Example Though we provide the redirect_uri parameter, we encourage you to register and use the redirect URL described in Step 3 over simply redirecting users to the parameter s value. direct_uri=https%3a%2f%2fifttt.com%2fchannels%2fexample_channel%2fauthorize&s cope=ifttt&state=a00caec8dbd08e50 Response After the user is redirected to your authorization request endpoint, you should authenticate the user and prompt to grant IFTTT access to the user s resources on your service. Authorization grant Once a user authorizes IFTTT, you should redirect the user to IFTTT s channel authorization URL along with an authorization code which IFTTT can exchange for a bearer token in the next step. Redirect URL The `channel_slug` is a string used to represent your service in URLs. You can set it in your service configuration. Parameters code state The authorization code you generated. The anti-forgery token provided by IFTTT in Step 2. Example

6 ate=a00caec8dbd08e50 User denies IFTTT Should the user deny IFTTT access to your service, you should redirect them to IFTTT indicating access was denied. Request URL channel_slug is a string used to represent your service in URLs. You can set it in your service configuration. Parameters Example error access_denied Token exchange Request After IFTTT has received an authorization code for the user, it will make a POST request to your OAuth2 Token URL, specified in the Service Authentication settings, and exchange the code for an access token. Body Parameters grant_type authorization_code code The authorization code generated in Step 3. client_id IFTTT s client ID for your service as set in your service configuration. client_secret

7 IFTTT s client secret for your service as set in your service configuration. redirect_uri channel_slug is a string used to represent your service in URLs. You can set it in your service configuration. Example POST /oauth2/token /1.1 Host: api.example-service.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=67a8ad c1&client_id=83465ab42&clien t_secret=c4f7defe91df9b23&redirect_uri=https%3a//ifttt.com/channels/channel_s lug/authorize Response If the authorization code is not valid, respond with a 401 status code and error response body. If the the authorization code is valid, provide the following response: Status 200 Headers Content-Type application/json; charset=utf-8 Body token Bearer access_token A token IFTTT will use to make authenticated calls to your API. refresh_token

8 Example (optional) If enabled, refresh token IFTTT will use to refresh access tokens. / OK Content-Type: application/json; charset=utf-8 { "token_type": "Bearer", "access_token": "b29a71b4c58c22af116578a6be6402d2" } Refresh Tokens You can indicate that your API uses refresh tokens under the Authentication tab. IFTTT will continue to use an access token until a 401 is received indicating the token is no longer valid. Once this occurs IFTTT will attempt to obtain a new access token using a refresh token via the token refresh endpoint before attempting the request again. Please note that refresh tokens cannot have a time-based expiry. The only time it is technically permissible for a refresh token to expire is after an access token has been refreshed. At that time, it is acceptable to return a new refresh token; however, we require that the previous refresh token not immediately expire. Token refresh Request After token expiry, IFTTT will make a POST request to your OAuth2 Token Endpoint, specified in the Service Authentication settings, and use the refresh token to retrieve a new access token.

9 Method POST URL OAuth2 Token Endpoint Headers Content-Type application/x-www-form-urlencoded Body grant_type refresh_token client_id IFTTT s client ID for your service as set in your service configuration. client_secret IFTTT s client secret for your service as set in your service configuration. refresh_token The refresh token retrieved in Step 4 of the Authentication Flow Example POST /oauth2/token /1.1 Host: api.example-service.com Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&client_id=83465ab42&client_secret=c4f7defe91df9b23&r efresh_token=c d9879ffeadfcc233effafb23bbdbfe Response If the refresh token is not valid, respond with a 401 status code and error response body. If the the refresh token is valid, provide the following response: Status 200

10 Headers Content-Type: application/json; charset=utf-8 Body access_token The updated access token. Example / OK Content-Type: application/json; charset=utf-8 { "access_token": "c547cdfecf7e86cde678bc87de6fc87", "refresh_token": "d7676beda76c bac98cba799" } User information Request After acquiring an access token, IFTTT will make a request to your user information endpoint. This information is considered private, and will only be displayed to the user who activated your service. Occasionally, IFTTT will make requests to this endpoint to verify that the user s access token is still valid. Method GET URL {{api_url_prefix}}/ifttt/v1/user/info Headers Authorization: Bearer {{user_access_token}}

11 X-Request-ID: {{random_uuid}} Body access_token The updated access token. Example GET /ifttt/v1/user/info /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 X-Request-ID: 434d757081c94013b1b28f2087d28a98 Response Requests to the user information endpoint should generate the following response: Status 200 Headers Content-Type: application/json; charset=utf-8 The body of the response is a JSON object with one top-level field, data, with three fields: Body name id (string) Full name, username, , or other identification to display to the user.

12 url (string) Username, , number, or other identification to uniquely identify the resource owner within your service. (optional string) URL to user s dashboard or configuration page on your service s website. Example / OK Content-Type: application/json; charset=utf-8 { "data": { "name": "Walter White", "id": "heisenberg", "url": " } } As with all other endpoints which require authentication via access token, you should return a 401 status to indicate that the access token is invalid or expired. Triggers Each trigger requires a unique API endpoint. For each Applet using a given trigger, IFTTT will poll that trigger s endpoint once about every 15 minutes. For each new item returned by the trigger, IFTTT will fire the Applet s associated action. A trigger endpoint should return (by default) up to the 50 most recent events, regardless of whether or not we have seen them before. The number of returned items can be overriden by us by specifying a limit parameter in the request. Please do not limit the number of events returned except as specified by the limit parameter in the request. Events should remain on the timeline indefinitely and should not expire, although they may roll off the bottom of the list once the timeline exceeds 50 items.

13 Note that if the Realtime API is used for a given trigger, it will be polled at a longer period. Request To fetch new items IFTTT will make the following request to your trigger endpoints: Method POST URL {{api_url_prefix}}/ifttt/v1/triggers/{{trigger_slug}} Headers Authenticated Services Authorization: Bearer {{user_access_token}} Content-Type: application/json X-Request-ID: {{random_uuid}} Headers Non-Authenticated Services Body IFTTT-Channel-Key: {{ifttt_channel_key}} Content-Type: application/json X-Request-ID: {{random_uuid}} trigger_identity (string) A unique identifier for this set of trigger fields for a given Applet (see Trigger Identity). triggerfields

14 limit user (object) Map of trigger field slugs to values. (optional integer) Maximum number of items to be returned, default 50. (object) Information about the IFTTT user related to this request. ifttt_source (optional object) Information about the personal Applet on IFTTT that triggered this request. If present, this will have an id uniquely identifying the Applet and a url pointing to a web page describing it. Note that only the user will be able to see this page, since personal Applets are private. In the future, these fields may point to an entity other than a personal Applet. This example excludes the optional limit parameter. Only the 50 most recent items should be returned, in descending chronological order. EXAMPLE: default limit POST /ifttt/v1/triggers/new_photo_in_album_with_hashtag /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 Content-Type: application/json X-Request-ID: 7f7cd9e0d bbf36da8fe24b449 { "trigger_identity": "92429d82a41e93048", "triggerfields": { "album_name": "Street Art", "hashtag": "banksy" }, "ifttt_source": { "id": "2", "url": " }, "user": { "timezone": "Pacific Time (US & Canada)" } }

15 This example provides the limit parameter. EXAMPLE: explicit limit POST /ifttt/v1/triggers/new_photo_in_album_with_hashtag /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 Content-Type: application/json X-Request-ID: 7f7cd9e0d bbf36da8fe24b449 { "triggerfields": { "album_name": "Street Art", "hashtag": "banksy" }, "limit": 10, "ifttt_source": { "id": "2", "url": " }, "user": { "timezone": "Pacific Time (US & Canada)" } } Response Responses contain an array of item objects. Items are a stream of unique events on a timeline, and each item has: One field for every ingredient in the trigger. A unique identifier used to prevent Applet from firing more than once on the same item. A timestamp in Unix seconds. Items in the stream must be in descending order by the timestamp. Responses should be structured as follows:

16 Status 200 Headers Content-Type application/json; charset=utf-8 For the Body you get a JSON object which contains an array, data, of item objects. Items have one key-value pair for each ingredient slug and value, and a meta object with two fields: BODY "data": [ { "slug 1": "value for ingredient 1", "slug 2": "value for ingredient 2",... "slug n": "value for ingredient n", "meta": { "id": "14b9-1fd2-acaa-5df5", //(string) a unique identifier for the item. "timestamp": // (integer) a Unix timestamp in seconds. } } ] Response Example / OK Content-Type: application/json; charset=utf-8 { "data": [ { "image_url": " "tags": "banksy, brooklyn", "posted_at": " T09:23:00-07:00" "meta": { "id": "14b9-1fd2-acaa-5df5", "timestamp": }

17 }, { "image_url": " "tags": "banksy, nyc", "posted_at": " T03:23:00-07:00" "meta": { "id": "ffb27-a63e-18e0-18ad", "timestamp": } } ] } Date and time ingredients Ingredients that use the Date or Date with time are timestamps in the W3 flavor of ISO8601 formats. Example: Date only Example: Date & Time T09:23:00Z T09:23:00-07:00 Trigger Identity A trigger_identity field is sent with every trigger endpoint request and uniquely identifies a given set of trigger fields and values for a user. While you might consider the trigger_identity a unique identifier for an individual user Applet, in reality if a user has multiple Applets with the same trigger fields/values they will all result in the same trigger_identity. The trigger_identity of a request can be thought of a compact form of what a trigger represents. While this field can safely be ignored, it becomes powerful when we use it to notify your API that a user no longer has any Applets that use a given trigger_identity because the Applet has been changed or otherwise deleted.

18 To notify your API that a given trigger_identity is no longer in use, the IFTTT API will make the following call to your API: Request Please note that your implementation of this endpoint is completely optional. If you are not interested in these notifications, you can simply ignore these requests and return a 404. Method Delete URL {{api_url_prefix}}/ifttt/v1/triggers/{{trigger_slug}}/trigger_identity/ {{trigger_identity}} Headers (authenticated services) Authorization: Bearer {{user_access_token}} Content-Type: application/json X-Request-ID: {{random_uuid}} Example DELETE /ifttt/v1/triggers/new_photo_in_album_with_hashtag/trigger_identity/92429d82a 41e93048 /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 Content-Type: application/json X-Request-ID: 7f7cd9e0d bbf36da8fe24b449

19 Example The use of the trigger_identity and corresponding DELETE endpoint is entirely up to you, but it comes in handy with services and devices that work in a publish/subscribe mode. Take the following scenario: 1. A user creates an Applet (or many Applets) that trigger on Check Engine Light. 2. The trigger endpoint is called and the API stores the trigger_identity for that user and associates that value with a Check Engine Light event on their vehicle. 3. The API notifies the vehicle that it wants to subscribe to Check Engine Light events and the vehicle begins sending this data to the cloud. At some point in the future 1. A user deletes or alters an Applet such that they no longer have any Applets that trigger on the event Check Engine Light. 2. IFTTT calls the DELETE endpoint. 3. The API does a lookup on trigger_identity for that user and notifies the associated vehicle to stop sending Check Engine Light events. 4. The API may then clean up or remove the storage of all the events associated with Check Engine Light for that user. As you can see, the trigger_identity field and corresponding DELETE endpoint can be used as a way to support a publish/subscribe scenario for events. Realtime API With IFTTT s Realtime API, you can have Applets involving user-oriented triggers from your service run near-instantly. Simply write a hook to notify IFTTT of any changes related to a given user which would correspond to a trigger they may be using. Rather than sending data directly, the Realtime API is used to notify IFTTT that there are new events available at your service for a specific user_id or trigger identity that we can then fetch through polling.

20 If you notify IFTTT that you are utilizing the Realtime API, we can limit the load on your service by polling less frequently. Request You can find your Service Key under the Details tab. Include it in your IFTTT-Channel-Key header to immediately start making Realtime requests. We also recommend that you send an X-Request-ID header with a UUID. Should the need to debug arise in the future, this will help reconcile server logs. Method POST URL Headers IFTTT-Channel-Key: {{ifttt_channel_key}} Content-Type: application/json X-Request-ID: {{random_uuid}} A JSON object which contains an array, data, of objects which each have a user_id or trigger_identity: Body data[user_id] (string) The same id for the user that is returned by your user information endpoint. data[trigger_identity]

21 (string) A unique identifier for a given set of trigger fields, sent to your API with every trigger endpoint request. Using trigger_identity will improve the performance of your integration with IFTTT. When the IFTTT Realtime API receives a user_id each of that user's triggers must be polled for, even though likely only a few of them have fresh data. For example, if a user had 100 Applets using your service's triggers, when that user_id is sent to the Realtime API IFTTT will need to run 100 checks for fresh data. This is a lot of extra time spent processing for both you and IFTTT, and reducing this time means your users' Applets will run faster. By using trigger_identity, IFTTT can poll your service for only the relevant fresh data. The Realtime request can contain up to 1000 user_ids and/or trigger_identities, although generally one would send either all user_ids or all trigger_identitys: Example POST /v1/notifications /1.1 Host: realtime.ifttt.com IFTTT-Channel-Key: WlWFGKXFsXBaFMt8yZ7aLOafdqo7mAhY Content-Type: application/json X-Request-ID: 619fd42930f74b78abc4394ca7bfec5b { "data": [ { "user_id": " " }, { "user_id": " " }, { "trigger_identity": "c5559d12d393b25c140364d891292e a5" },... ] }

22 Trigger fields Trigger fields can have dynamic options and dynamic validation. Each dynamic option and validation requires a unique endpoint. Trigger field dynamic options Options have both a label, which the user sees, and a value, which is sent when the trigger is executed. Options can be placed into categories; users may select categorized options but may not select the category itself. See the example exchange below for more information on how to present the options to IFTTT. Request For drop-down selector trigger fields, you can dynamically provide userspecific options. Each time the drop-down is displayed, IFTTT will fetch a list of options from your trigger field s dynamic options endpoint. Method POST URL {{api_url_prefix}}/ifttt/v1/triggers/{{trigger_slug}}/fields/{{trigger_ field_slug}}/options HEADERS: authenticated services Authorization: Bearer {{user_access_token}} X-Request-ID: {{random_uuid}} HEADERS: non-authenticated services

23 IFTTT-Channel-Key: {{ifttt_channel_key}} X-Request-ID: {{random_uuid}} Example POST /ifttt/v1/triggers/new_photo_in_album_with_hashtag/fields/album_name/options /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 X-Request-ID: 37ccb881af5542fe8c5534e9744b6116 {} Response Your trigger field s dynamic options endpoint should generate the following response: Status 200 Headers Content-Type: application/json; charset=utf-8 A JSON object which contains an array, data, of option objects: Body label (string) A user-facing label. value

24 Example (string) The actual field value. / OK Content-Type: application/json; charset=utf-8 { "data": [ { "label": "Street Art", "value": "12345" }, { "label": "Technology", "value": "43245" }, { "label": "Animals", "values": [ { "label": "Cats", "value": "32143" }, { "label": "Dogs", "value": "51231" } ] } ] } Trigger field dynamic validation Request For text trigger fields, you can dynamically validate user input. IFTTT will make the following request to your service API: Method

25 URL POST {{api_url_prefix}}/ifttt/v1/triggers/{{trigger_slug}}/fields/{{trigger_ field_slug}}/validate HEADERS: authenticated services Authorization: Bearer {{user_access_token}} X-Request-ID: {{random_uuid}} HEADERS: non-authenticated services Body IFTTT-Channel-Key: {{ifttt_channel_key}} X-Request-ID: {{random_uuid}} value (string) User input to be validated { Example POST /ifttt/v1/triggers/new_photo_in_album_with_hashtag/fields/album_name/validate /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 Content-Type: application/json X-Request-ID: b959f481ef4f4a8ab0ec414f

26 } "value": "Street Art" Response Your trigger field s dynamic validation endpoint should generate the following response: Status 200, regardless of whether or not the user input is valid Headers Content-Type: application/json; charset=utf-8 For the body you get a JSON object which contains an object, data: Body data[valid] (boolean) Validity of user s input. data[message] (optional string) Explanation to display to user if input was invalid. Example: Valid Input / OK Content-Type: application/json; charset=utf-8 { "data": { "valid": true } } Example: Invalid Input / OK

27 Content-Type: application/json; charset=utf-8 { "data": { "valid": false, "message": "Sorry, no album exists with the name \"Street Art\"." } } Actions Each action requires a unique API endpoint. Request For each new trigger item, IFTTT will push data to your action endpoint with the following request structure: Method POST URL {{api_url_prefix}}/ifttt/v1/actions/{{action_slug}} HEADERS: authenticated services Authorization: Bearer {{user_access_token}} X-Request-ID: {{random_uuid}} HEADERS: non-authenticated services IFTTT-Channel-Key: {{ifttt_channel_key}}

28 Body X-Request-ID: {{random_uuid}} actionfields (object) Map of action field slugs to values. user (object) Information about the IFTTT user related to this request. ifttt_source (optional object) Information about the personal Applet on IFTTT that triggered this request. If present, this will have an id uniquely identifying the Applet and a url pointing to a web page describing it. Note that only the user will be able to see this page, since personal Applets are private. In the future, these fields may point to an entity other than a personal Applet. Example POST /ifttt/v1/actions/new_status_update /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 Content-Type: application/json X-Request-ID: 1d21c3cd2ed8441ea269dd554d2c8e54 { "actionfields": { "title": "New Banksy photo!", "body": "Check out a new Bansky photo: }, "ifttt_source": { "id": "2", "url": " }, "user": { "timezone": "Pacific Time (US & Canada)" } }

29 Response Your action endpoint should generate the response below: Status 200 Headers Content-Type: application/json; charset=utf-8 A JSON object which contains an array, data, of a single item object: data[0][id] (string) A database ID, timestamp, URL, or other value which uniquely identifies the resource created or modified during action execution. data[0][url] (optional string) URL to the created or modified resource. Example / OK Content-Type: application/json; charset=utf-8 { "data": [ { "id": "234325", "url": " } ] } Skipping Records If an action fails and returns an error, IFTTT will retry the same record several times. If the action continues to fail processing that record, the offending record will eventually be skipped. However, the action can specify

30 that a record be skipped immediately by responding with status code 400 and a special error object. It should do this when a record will simply never be successfully processed because it is invalid or unacceptable. For example, a Post Comment action may want to skip over any records that have an empty comment. Note that this does not include syntactic errors in the requests or problems beyond just the individual record and its action fields, including authentication. A skip error has a property status that must always be set to "SKIP". It should also have a property message. The message will be displayed to the user in the Applet s Activity Log. 400 responses may have multiple error objects; any additional SKIP objects after the first will be ignored. Example / Bad request Content-Type: application/json; charset=utf-8 { "errors": [ { "status": "SKIP", "message": "Audio file size too big" } ] } Action fields Action fields can have dynamic options. Each dynamic option requires a unique endpoint. Unlike trigger fields, action fields do not currently support dynamic validation. Action field dynamic options Options have both a label, which the user sees, and a value, which is sent when the action is executed. Options can be placed into categories; users may select categorized options but may not select the category itself. See

31 the example exchange below for more information on how to present the options to IFTTT. Request For drop-down selector action fields, you can dynamically provide userspecific options. Each time the action field is displayed, IFTTT will fetch a list of options from your action field s dynamic options endpoint: Method POST URL {{api_url_prefix}}/ifttt/v1/actions/{{action_slug}}/fields/{{action_fie ld_slug}}/options HEADERS: authenticated services Authorization: Bearer {{user_access_token}} X-Request-ID: {{random_uuid}} HEADERS: non-authenticated services IFTTT-Channel-Key: {{ifttt_channel_key}} X-Request-ID: {{random_uuid}} An empty JSON object Body

32 {} Example POST /ifttt/v1/actions/post_photo_to_album/fields/album_name/options /1.1 Host: api.example-service.com Authorization: Bearer b29a71b4c58c22af116578a6be6402d2 X-Request-ID: 9f99e73452cd40198cb6ce9c1cde83d6 {} Response Your action field s dynamic options endpoints should generate the following response: Status 200 Headers Content-Type: application/json; charset=utf-8 For the body you will get a JSON object which contains an array, data, of option objects: Body data[label] (string) A user-facing label. data[value] (string) The actual field value. Example / OK

33 Content-Type: application/json; charset=utf-8 { "data": [ { "label": "Street Art", "value": "12345" }, { "label": "Technology", "value": "43245" }, { "label": "Animals", "values": [ { "label": "Cats", "value": "32143" }, { "label": "Dogs", "value": "51231" } ] } ] } Service status Provide an API endpoint which IFTTT can periodically check for your service s availability. This endpoint is not user-specific, and thus does not require an access token. Request IFTTT will make the following request to check you service s API status: Method GET URL

34 HEADERS {{api_url_prefix}}/ifttt/v1/status IFTTT-Channel-Key: {{ifttt_channel_key}} X-Request-ID: {{random_uuid}} Example GET /ifttt/v1/status /1.1 Host api.example-service.com IFTTT-Channel-Key: vfrqpgzbmzjb8jpp3mbfqodt X-Request-ID: 0715f98e65f749aba2fc243eac1e3c09 Response The service status endpoint should generate the following response: Status 200 or 503 Body none Example: service OK / OK Example: service unavailable

35 / Unavailable