FORMAT: 1A HOST: https://sagefy.org/

Sagefy Web Service API

This document outlines the endpoints for Sagefy and their specifications.

Errors will appear in the following format, along with the appropriate status code (400, 401, 403, 404):

  "errors": [{
    "name": "field",
    "message": "The reason for the error."

Welcome [/s]

Welcome Message [GET]

Welcomes the developer to the Sagefy service.

Users [/s/users]

Create a new user [POST]

Create a new user account.

Returns a 400 if there are errors, such as email already used or password too short.

User [/s/users/{id}]

Get a user [GET]

Get the user information given a user ID.

email and email_frequency are private and only available to the self user.

Returns a 404 if user is not found.

current may be substituted for id. In that case, returns a 401 if a user is not logged in.

Update a user [PUT]

Update the user. Must be the current user.

Return a 404 if no user matching that ID. Return 401 if not the current user. Return 400 for parameter issues.

Log in or out user [/s/sessions]

Log in as user [POST]

Log in as an existing user.

Returns 404 if the user by name is not found. Returns a 400 if the password is not valid.

Log out as user [DELETE]

Log out of the current user.

Password Token [/s/password_tokens]

Create Password Token [POST]

Email a token to be able to reset the password.

Return a 404 if it cannot find the user’s email.

Create Password [/s/users/{user_id}/password]

Create a password [POST]

Update the user’s password. Must have a matching and timely token.

200 also logs in user. 404 if not a valid user ID. 403 if the token doesn’t match.

User Subjects [/s/users/{id}/subjects]

Get all of users’ subjects [GET]

Get the list of learner’s subjects.

401 if not logged in. 403 if not current user.

User Subject [/s/users/{id}/subjects/{id}]

Add a user subject [POST]

Add a subject to the learner’s list.

401 if not logged in. 403 if not current user. 404 if subject not found. 409 if already added.

Remove a user subject [DELETE]

Remove a subject from the learner’s list.

401 if not logged in. 403 if not current user. 404 if subject not found.

Select a user subject [PUT]

Selects a subject for the user to engage.

Card [/s/cards/{id}]

Cards are the smallest entity in the Sagefy data structure system. A card represents a single learner activity.

Get card [GET]

Get a specific card given an ID. Show all relevant data, but not used for the learning interface.

Always returns the latest accepted version. 404 if card not found.

Card for Learning [/s/cards/{id}/learn]

Some data is filtered out, such as feedback and which answer is correct.

Get card [GET]

Render the card’s data, ready for learning.

Card Responses [/s/cards/{id}/responses]

Create a card response [POST]

Record and process a learner’s response to a card.

Card Versions [/s/cards/{card_id}/versions]

Get card versions [GET]

Unit [/s/units/{id}]

A unit is the medium size in the Sagefy data structure system. A unit represents a unit of learning activity.

Get unit info [GET]

Get a specific unit given an ID.

Always returns the latest accepted version. 404 if card not found.

Unit Versions [/s/units/{unit_id}/versions]

Get unit versions [GET]

Subject [/s/subjects/{id}]

A subject is a collection of units and other subjects.

Get subject information [GET]

Get a specific subject given an ID.

Subject Versions [/s/subjects/{subject_id}/versions]

Get subject versions [GET]

Subject Tree [/s/subjects/{id}/tree]

Get subject [GET]

Render the tree of units that exists within a subject.

404 if subject not found.

Subject’ Units [/s/subjects/{id}/units]

Get subject units [GET]

Render the units that exist within the subject.

Specifically, present a small number of units the learner can choose from.

401 if not logged in. 404 if subject not found. 400 if it doesn’t make sense.

Subject’ Unit [/s/subjects/{id}/units/{id}]

Choose unit [POST]

Updates the learner’s information based on the unit they have chosen.

401 if not logged in. 404 if subject or unit not found. 400 if it doesn’t make sense.

Next [/s/next]

Next is an abstract resource which only determines one thing: where to go next.

Next [GET]

Tell the learner where to go next.

Can lead to a card, tree, or choose unit screen.

Search [/s/search]

Site-wide search for cards, units, subjects, users, topics, and posts.

Search [GET]

Search for entities.

Topics [/s/topics]

Topics, or threads, are the entity that hold a conversation, a list of posts. The Topic service handles both topics and posts, as posts always belong to a single topic.

Create topic [POST]

Create a new topic. The first post (proposal, flag) must be provided. Flag: if a flag for the same reason exists for the entity, create a vote there instead.

When creating a topic, you must also submit information for a valid post. There are four post kinds. All require the “kind” field filled out. Replies to ID is optional. Proposals also require an entity version ID, name, status, and action. Votes have optional bodies, but require “replies_to_id” and “response”. Flag requires entity version ID, name, reason, and status.

Returns 400 if missing or invalid topic or post information. Return 401 if not logged in as a user.

Topic [/s/topics/{id}]

Update topic [PUT]

Update the topic. Only the name can be changed. Only by original author.

401 if not logged in. 404 if topic by ID not found. 403 if not user’s own topic. 400 if there’s issues with the name field.

Posts [/s/topics/{id}/posts]

Get posts [GET]

Get a reverse chronological listing of posts for given topic. Includes topic meta data and posts (proposals, votes, flags). Paginates.

Returns 404 if topic not found. Posts can be one of post, proposal, vote, or flag. The kind changes the field available.

Create post [POST]

Create a new post on a given topic. Accounts for posts, proposals, votes, and flags. Proposal: must include entity (card, unit, subject) information. Vote: must refer to a proposal.

401 if not logged in. 404 if topic not found. 400 if issue presented with content.

Post [/s/topics/{id}/post/{id}]

Update post [PUT]

Update an existing post. Must be one’s own post. For proposals: The only field that can be updated is the status; the status can only be changed to declined, and only when the current status is pending or blocked.

401 if not logged in. 403 if not own post. 400 if issues with content.

Follows [/s/follows]

Follows allow users to subscribe to updates on cards, units, and subjects.

List follows [GET]

Follow [POST]

Current user follows an entity, topic, or proposal.

Return 401 if not logged in. Return 400 if content issues.

Follow [/s/follows/{id}]

Unfollow [DELETE]

Remove a follow. Must be current user’s own follow.

Return 404 if it doesn’t find that follow. Return 401 if not logged in. Return 403 if not own follow. Return 400 if other errors.

Notices [/s/notices]

Notices provide updates to users on cards, units, and subjects they follow.

List notices [GET]

List notices for current user.

Returns a 401 if there’s no user currently logged in.

Notice [/s/notices/{id}]

Mark notice as read/unread [PUT]

Mark notice as read. Must be logged in as user, provide a valid ID, and own the notice. Return notice.

Returns 401 if not logged in. Returns 404 if notice not found. Returns 403 if not user’s own notice. Returns 400 if issues saving to the database.