retoor
cae139ead9
DevPlace CI / test (push) Failing after 28m20s
Also streamline the top navigation: drop the Tools dropdown, make Quizzes and Battles icon-only entries, and remove the Workspace, Containers and Editor entry points from the project detail page.
297 lines
11 KiB
Python
297 lines
11 KiB
Python
# retoor <retoor@molodetz.nl>
|
|
|
|
from .._shared import (
|
|
BOOKMARK_TARGETS,
|
|
NOTE_TARGETS,
|
|
REACTION_TARGETS,
|
|
VOTE_TARGETS,
|
|
endpoint,
|
|
field,
|
|
)
|
|
from devplacepy.constants import REACTION_EMOJI
|
|
|
|
GROUP = {
|
|
"slug": "social-actions",
|
|
"title": "Votes, Reactions, Bookmarks, Notes & Polls",
|
|
"intro": """
|
|
# Votes, Reactions, Bookmarks, Notes & Polls
|
|
|
|
Lightweight engagement actions. The vote/reaction/bookmark POST endpoints here are **toggles** -
|
|
sending the same action again removes it. They return JSON when called with
|
|
`X-Requested-With: fetch` (sent automatically by the panels below); the
|
|
[Conventions & Errors](/docs/conventions.html) page explains that header rule and the response
|
|
envelope.
|
|
|
|
Personal notes are private, per-user annotations attached to a piece of content - only you can
|
|
ever see your own notes.
|
|
|
|
Every endpoint follows the shared [Conventions & Errors](/docs/conventions.html) (auth, content
|
|
negotiation, pagination, status codes); see [Authentication](/docs/authentication.html) for the
|
|
four ways to sign requests.
|
|
""",
|
|
"endpoints": [
|
|
endpoint(
|
|
id="votes-cast",
|
|
method="POST",
|
|
path="/votes/{target_type}/{target_uid}",
|
|
title="Cast or toggle a vote",
|
|
summary="Upvote or downvote a target. Re-sending the same value, or sending 0, removes the vote.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="form",
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"Type of content being voted on.",
|
|
VOTE_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the target.",
|
|
),
|
|
field(
|
|
"value",
|
|
"form",
|
|
"enum",
|
|
True,
|
|
"1",
|
|
"1 to upvote, -1 to downvote, 0 to retract your existing vote.",
|
|
["1", "-1", "0"],
|
|
),
|
|
],
|
|
sample_response={"net": 3, "up": 4, "down": 1, "value": 1},
|
|
),
|
|
endpoint(
|
|
id="reactions-toggle",
|
|
method="POST",
|
|
path="/reactions/{target_type}/{target_uid}",
|
|
title="Toggle an emoji reaction",
|
|
summary="Add or remove an emoji reaction on a target.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="form",
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"Type of content being reacted to.",
|
|
REACTION_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the target.",
|
|
),
|
|
field(
|
|
"emoji",
|
|
"form",
|
|
"string",
|
|
True,
|
|
REACTION_EMOJI[0],
|
|
"Any single emoji character. Re-sending the same one removes it.",
|
|
),
|
|
],
|
|
sample_response={
|
|
"counts": {REACTION_EMOJI[0]: 2},
|
|
"mine": [REACTION_EMOJI[0]],
|
|
},
|
|
),
|
|
endpoint(
|
|
id="bookmarks-toggle",
|
|
method="POST",
|
|
path="/bookmarks/{target_type}/{target_uid}",
|
|
title="Toggle a bookmark",
|
|
summary="Save or unsave a target to your bookmarks.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="none",
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"Type of content to bookmark.",
|
|
BOOKMARK_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the target.",
|
|
),
|
|
],
|
|
sample_response={"saved": True},
|
|
),
|
|
endpoint(
|
|
id="bookmarks-saved",
|
|
method="GET",
|
|
path="/bookmarks/saved",
|
|
title="View saved bookmarks",
|
|
summary="Render your saved content. Returns an HTML page.",
|
|
auth="user",
|
|
interactive=True,
|
|
params=[
|
|
field(
|
|
"before",
|
|
"query",
|
|
"string",
|
|
False,
|
|
"",
|
|
"Pagination cursor (created_at of the last item).",
|
|
)
|
|
],
|
|
notes=[
|
|
"Bookmarks target posts, projects, gists, and news; see [Posts, Comments, Projects, Gists & News](/docs/content.html)."
|
|
],
|
|
),
|
|
endpoint(
|
|
id="notes-set",
|
|
method="POST",
|
|
path="/notes/{target_type}/{target_uid}",
|
|
title="Add or update a personal note",
|
|
summary="Save a private note on a target. Only you can ever see it.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="form",
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"Type of content to annotate.",
|
|
NOTE_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the target.",
|
|
),
|
|
field(
|
|
"content",
|
|
"form",
|
|
"string",
|
|
True,
|
|
"Remember to check this later.",
|
|
"Note body, up to 4000 characters. Sending again on the same target replaces the note.",
|
|
),
|
|
],
|
|
sample_response={"uid": "NOTE_UID", "content": "Remember to check this later."},
|
|
),
|
|
endpoint(
|
|
id="notes-delete",
|
|
method="POST",
|
|
path="/notes/{target_type}/{target_uid}/delete",
|
|
title="Delete a personal note",
|
|
summary="Remove your private note from a target.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="none",
|
|
params=[
|
|
field(
|
|
"target_type",
|
|
"path",
|
|
"enum",
|
|
True,
|
|
"post",
|
|
"Type of content the note is on.",
|
|
NOTE_TARGETS,
|
|
),
|
|
field(
|
|
"target_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POST_UID",
|
|
"UID of the target.",
|
|
),
|
|
],
|
|
sample_response={"deleted": True},
|
|
),
|
|
endpoint(
|
|
id="notes-saved",
|
|
method="GET",
|
|
path="/notes/saved",
|
|
title="View your personal notes",
|
|
summary="Render your saved notes. Returns an HTML page.",
|
|
auth="user",
|
|
interactive=True,
|
|
params=[
|
|
field(
|
|
"before",
|
|
"query",
|
|
"string",
|
|
False,
|
|
"",
|
|
"Pagination cursor (created_at of the last item).",
|
|
)
|
|
],
|
|
notes=[
|
|
"Notes target posts, projects, gists, and news; see [Posts, Comments, Projects, Gists & News](/docs/content.html).",
|
|
"Nobody else can ever see your notes, not even the author of the content you annotated.",
|
|
],
|
|
),
|
|
endpoint(
|
|
id="polls-vote",
|
|
method="POST",
|
|
path="/polls/{poll_uid}/vote",
|
|
title="Vote in a poll",
|
|
summary="Cast, change, or clear your vote on a poll option.",
|
|
auth="user",
|
|
ajax=True,
|
|
encoding="form",
|
|
params=[
|
|
field(
|
|
"poll_uid",
|
|
"path",
|
|
"string",
|
|
True,
|
|
"POLL_UID",
|
|
"UID of the poll.",
|
|
),
|
|
field(
|
|
"option_uid",
|
|
"form",
|
|
"string",
|
|
True,
|
|
"OPTION_UID",
|
|
"UID of the chosen option.",
|
|
),
|
|
],
|
|
notes=[
|
|
"You hold at most one vote per poll, and only your latest vote counts. "
|
|
"Voting a different option replaces your previous choice; voting your current "
|
|
"option again removes the vote.",
|
|
],
|
|
sample_response={
|
|
"question": "Best editor?",
|
|
"options": [{"uid": "OPTION_UID", "label": "Vim", "votes": 5}],
|
|
"total": 5,
|
|
"voted": "OPTION_UID",
|
|
},
|
|
),
|
|
],
|
|
}
|