From ec66bfb0cd287702407d7e8e9858f6f8e81a65e8 Mon Sep 17 00:00:00 2001 From: Alys Date: Fri, 3 Apr 2015 21:24:48 +1000 Subject: [PATCH] Specify which API routes need no authentication. Specify task types for full scoring route. For simple scoring, state that it's only Habits and explain that other tasks can use full scoring. --- website/src/routes/apiv2.coffee | 8 ++++---- website/views/static/api.jade | 3 ++- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/website/src/routes/apiv2.coffee b/website/src/routes/apiv2.coffee index 479521d054..ad2c457129 100644 --- a/website/src/routes/apiv2.coffee +++ b/website/src/routes/apiv2.coffee @@ -35,13 +35,13 @@ module.exports = (swagger, v2) -> '/status': spec: - description: "Returns the status of the server (up or down)" + description: "Returns the status of the server (up or down). Does not require authentication." action: (req, res) -> res.json status: "up" '/content': spec: - description: "Get all available content objects. This is essential, since Habit often depends on item keys (eg, when purchasing a weapon)." + description: "Get all available content objects. This is essential, since Habit often depends on item keys (eg, when purchasing a weapon). Does not require authentication." parameters: [ query("language","Optional language to use for content's strings. Default is english.","string") ] @@ -49,7 +49,7 @@ module.exports = (swagger, v2) -> '/content/paths': spec: - description: "Show user model tree" + description: "Show user model tree. Does not require authentication." action: user.getModelPaths "/export/history": @@ -68,7 +68,7 @@ module.exports = (swagger, v2) -> "/user/tasks/{id}/{direction}": spec: #notes: "Simple scoring of a task." - description: "Simple scoring of a task. This is most-likely the only API route you'll be using as a 3rd-party developer. The most common operation is for the user to gain or lose points based on some action (browsing Reddit, running a mile, 1 Pomodor, etc). Call this route, if the task you're trying to score doesn't exist, it will be created for you. When random events occur, the user._tmp variable will be filled. Critical hits can be accessed through user._tmp.crit. The Streakbonus can be accessed through user._tmp.streakBonus. Both will contain the multiplier value. When random drops occur, the following values are available: user._tmp.drop = {text,type,dialog,value,key,notes}" + description: "Simple scoring of a task (Habit, Daily, To-Do, or Reward). This is most-likely the only API route you'll be using as a 3rd-party developer. The most common operation is for the user to gain or lose points based on some action (browsing Reddit, running a mile, 1 Pomodor, etc). Call this route, if the task you're trying to score doesn't exist, it will be created for you. When random events occur, the user._tmp variable will be filled. Critical hits can be accessed through user._tmp.crit. The Streakbonus can be accessed through user._tmp.streakBonus. Both will contain the multiplier value. When random drops occur, the following values are available: user._tmp.drop = {text,type,dialog,value,key,notes}" parameters: [ path("id", "ID of the task to score. If this task doesn't exist, a task will be created automatically", "string") path("direction", "Either 'up' or 'down'", "string") diff --git a/website/views/static/api.jade b/website/views/static/api.jade index f4bbd576f3..1ed3be1079 100644 --- a/website/views/static/api.jade +++ b/website/views/static/api.jade @@ -86,8 +86,9 @@ html li POST to the URL /api/v2/user/tasks/{id}/{direction} ul li {direction} is 'up' or 'down' - li {id} is a unique identifier for a task, which you make up, consisting of lowercase letters. Try to make it something common, like 'productivity' or 'fitness' - because other services may piggy-back off your task. For example, the Chrome extension down-scores a productivity task when you visit vice websites (reddit, 9gag, etc). However, Pomodoro up-scores productivity when you complete a task. So the two services share a single task to score your overall productivity. If the task doesn't yet exist, it is created the first time you POST to this URL. + li {id} is a unique identifier for a Habit, which you make up, consisting of lowercase letters. Try to make it something common, like 'productivity' or 'fitness' - because other services may piggy-back off your Habit. For example, the Chrome extension down-scores a productivity Habit when you visit vice websites (reddit, 9gag, etc). However, Pomodoro up-scores productivity when you complete a Pomodoro task. So the two services share a single Habit to score your overall productivity. If the Habit doesn't yet exist, it is created the first time you POST to this URL. li apiToken (POST body) required + p A more advanced version that allows modification of other types of tasks is available in the /user/tasks/{id}/{direction} route in the full API below. h2 Full API p All API requests should be prefaced by https://habitrpg.com. Every authenticated request should include two headers. Your api key (x-api-key) and your user id (x-api-user). Do not include {} braces in your header (-H 'x-api-user: a94b6d9d-6b64-43ae-856c-2c3f211bd426') h2 Requirements: