Skip to content
This repository has been archived by the owner on Apr 19, 2022. It is now read-only.

Latest commit

 

History

History
293 lines (272 loc) · 9.74 KB

APIDocumentation.md

File metadata and controls

293 lines (272 loc) · 9.74 KB
Raw

API Documentation (API v1.0.0)

Making requests

All queries to the API need to be presented in this form: http://api.ctf.yummytacos.me/METHOD_NAME. Like this for example: http://api.ctf.yummytacos.me/tasks

API supports four ways of passing parameters in requests:

  • URL query string
  • application/x-www-form-urlencoded
  • application/json (except for uploading files)
  • multipart/form-data (use to upload files)

The response contains a JSON object. On success, an object in Endpoints section is returned. Otherwise, object with error_code and human-readable message is returned. Some errors may also have an optional String field key, which can help to handle the error.

Authentication

To use methods, which require authentication, confirmed account or admin rights, you must provide token as Authorization HTTP header like this: Authorization: Bearer <token>, where <token> is your token (you can get it by authenticating, see Endpoints section for more).

Endpoints

/about

Use this method to get information about this platform

Methods:

GET

About platform

Args:
  • Nothing
Returns:
  • name (String): Platform name
  • version (String): Platform version
  • license (String): Platform distribution license
  • license_url (String): Platform distribution license URL
  • repository (String): Platform repository URL
  • contact (String): Contact name in case of questions
  • contact_url (String): Contact URL in case of questions
  • uptime (Integer): Platform uptime (seconds)

/article

Use this method to retrieve article

Methods:

GET

Get article

Args:
  • id (Integer, required): Article ID
Returns:
  • article (Article): Article

/articles

Use this method to retrieve articles

Methods:

GET

Get articles

Args:
  • category_id (Integer, optional): If provided, filter articles by category, otherwise return all articles
Returns:
  • articles (List<Article>): Resulting list of articles

/auth

Use this method to authenticate in platform.

Methods:

POST

Authenticate

Args:
  • username (String, required): Username for the user
  • password (String, required): Password for the user
Returns:
  • token (String): Token which can be used to authenticate API requests

/categories

Use this method to retrieve all categories

Methods:

GET

Get categories

Args:
  • Nothing
Returns:
  • categories (List<Category>): Resulting list of categories

/category

Use this method to retrieve category information

Methods:

GET

Get category

Args:
  • id (Integer, required): Category ID
Returns:
  • category (Category): Category

/recover

Use this method to recover account password

Methods:

POST

Request password recovery email or confirm password recovery

Args:
  • code (String, optional): If provided, try to recover account password, otherwise, request password recovery email
  • email (String, optional): Email of account to recover
  • url (String, optional): If provided, this URL will be used to provide alternative verification method
Returns:
  • token (String): If account password recovery was requested and it succeeded, token, which can be used to log in and change password, empty string otherwise

/register

Use this method to register in platform.

Methods:

POST

Register in platform. Send first request without captcha_id and captcha_data, then you will get captcha_id together with a "Captcha required" error. Solve it and send result as captcha_data back with captcha_id

Args:
  • username (String, required): Username. Must contain only latin letters, digits, underscores and dots
  • first_name (String, required): First name
  • last_name (String, optional): Last name
  • email (String, required): E-mail
  • password (String, required): Password
  • captcha_id (String, optional): ID of the captcha that can confirm your registration
  • captcha_data (String, optional): Solved captcha that can confirm your registration
Returns:
  • user_id (Integer): ID of successfully registered user

/task

Use this method to retrieve task information or to send flags for the task.

Methods:

GET

Get task

Args:
  • id (Integer, required): Task ID
Returns:
  • task (Task): Task
POST

Send task flag (requires authentication)

Args:
  • id (Integer, required): Task ID
  • flag (String, required): Task flag
Returns:
  • Nothing

/tasks

Use this method to retrieve list of tasks

Methods:

GET

Get tasks

Args:
  • Nothing
Returns:
  • tasks (List<Task>): Resulting list of tasks

/user

Use this method to retrieve information about the user

Methods:

GET

Get user info

Args:
  • id (Integer, optional): User ID. If not provided, returns info about current user
Returns:
  • user (User): User
PATCH

Edit current user info (requires authentication)

Args:
  • id (Integer, optional): User ID to edit (requires admin rights)
  • username (String, optional): New username
  • email (String, optional): New email. Resets confirmation status, if present
  • first_name (String, optional): New first name
  • last_name (String, optional): New last name
  • password (String, optional): New password
  • is_admin (Integer, optional): If this is set to 0, removes admin rights, else if this is set to 1, sets admin rights (requires admin rights)
Returns:
  • Nothing

/users

Use this method to retrieve all users.

Methods:

GET

Get users

Args:
  • Nothing
Returns:
  • users (List<User>): Resulting list of users

/verify

Use this method to verify user's email

Methods:

POST

Request email verification or verify email

Args:
  • code (String, optional): If provided, try to verify email, otherwise, request email verification (requires authentication)
  • url (String, optional): If provided, this URL will be used to provide alternative verification method
Returns:
  • Nothing

/docs

Use this method to retrieve API documentation

Methods:

GET

Get API documentation

Args:
  • method (String, optional): If provided, return documentation for this method, otherwise return documentation for all methods
Returns:
  • doc (Mapping<str, str>): Documentation in Markdown format. "_" key is documentation header, which describes how to make requests

/admin/article

Use this method to manage articles

Methods:

POST

Create new article (requires admin rights)

Args:
  • title (String, required): Article title
  • text (String, required): Article text
  • category (Integer, required): Category ID for article
Returns:
  • article (Article): Created article
PATCH

Edit article (requires admin rights)

Args:
  • id (Integer, required): Article ID
  • title (String, optional): New article title
  • text (String, optional): New article text
  • category (Integer, optional): New category ID for article
Returns:
  • article (Article): Edited article
DELETE

Delete article (requires admin rights)

Args:
  • id (Integer, required): Article ID
Returns:
  • Nothing

/admin/category

Use this method to manage categories

Methods:

POST

Create new category (requires admin rights)

Args:
  • name (String, required): Category name
Returns:
  • category (Category): Created category
PATCH

Edit category (requires admin rights)

Args:
  • id (Integer, required): Category ID
  • name (String, optional): New category name
Returns:
  • category (Category): Edited category
DELETE

Delete category (requires admin rights)

Args:
  • id (Integer, required): Category ID
Returns:
  • Nothing

/admin/task

Use this method to manage tasks.

Methods:

POST

Create or propose new task (requires confirmed account)

Args:
  • title (String, required): Task name
  • author (Integer, required): If provided, user ID of task author (cannot be set on task proposals), otherwise current user ID
  • category (String, required): Task category
  • points (Integer, required): Task points, must be positive
  • description (String, required): Task description
  • writeup (String, required): Task write-up (solution)
  • flag (String, required): Task flag
Returns:
  • task (Task): Created task
PATCH

Edit task (if user is admin, this also confirms task proposal) (requires confirmed account)

Args:
  • id (Integer, required): Task ID to edit
  • title (String, optional): New task name
  • author (Integer, optional): User ID of new task author
  • category (String, optional): New task category
  • points (Integer, optional): New task points, must be positive
  • description (String, optional): New task description
  • writeup (String, optional): New task write-up (solution)
  • flag (String, optional): New task flag
Returns:
  • task (Task): Edited task
DELETE

Delete task (requires confirmed account)

Args:
  • id (Integer, required): Task ID to delete
Returns:
  • Nothing

/admin/file

Use this method to manage task files

Methods:

POST

Send file and attach it to task (requires confirmed account)

Args:
  • task_id (Integer, required): Task ID
  • file (multipart/form-data, required): File
Returns:
  • file (File): Added file
DELETE

Delete file (requires confirmed account)

Args:
  • id (Integer, required): File ID to delete
Returns:
  • Nothing