Last active
June 23, 2017 11:16
-
-
Save ignar/bf7b4d68c7cd653d9fe4c437e281285a to your computer and use it in GitHub Desktop.
Brandslisten API V2.1
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
swagger: '2.0' | |
info: | |
version: "0.4" | |
title: Brandslisten API | |
description: | | |
API provided by Brandslisten GmbH | |
host: 0.0.0.0:10010 | |
basePath: / | |
schemes: | |
- http | |
consumes: | |
- application/json | |
produces: | |
- application/json | |
paths: | |
/sessions: | |
x-swagger-router-controller: mock | |
post: | |
description: | | |
Log in user using email and password credentials | |
produces: | |
- application/json | |
parameters: | |
- | |
name: email | |
in: formData | |
description: email of the user | |
required: true | |
type: string | |
format: string | |
- | |
name: password | |
in: formData | |
required: true | |
description: password of the user | |
type: string | |
format: password | |
tags: | |
- User | |
responses: | |
200: | |
description: Successful response | |
schema: | |
type: object | |
properties: | |
success: | |
type: boolean | |
description: Returns true value | |
auth_token: | |
description: JWT token of the user's session | |
type: string | |
email: | |
type: string | |
uuid: | |
type: string | |
format: uuid | |
401: | |
description: Not Authorized | |
schema: | |
type: object | |
properties: | |
success: | |
type: boolean | |
description: Returns false value | |
message: | |
type: string | |
description: Reason of failure | |
/users/{uuid}: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
Request Registered User profile by its UUID | |
produces: | |
- application/json | |
parameters: | |
- | |
name: uuid | |
in: path | |
description: Id of the user | |
required: true | |
type: string | |
format: uuid | |
tags: | |
- User | |
responses: | |
200: | |
description: Successful response | |
schema: | |
$ref: '#/definitions/User' | |
/users/{uuid}/statistic: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
Request users's statistic. Returns last user's activity | |
produces: | |
- application/json | |
parameters: | |
- | |
name: uuid | |
in: path | |
description: Id of the user | |
required: true | |
type: string | |
format: uuid | |
tags: | |
- User | |
responses: | |
200: | |
description: Successful response | |
schema: | |
$ref: '#/definitions/UserStatistic' | |
/users: | |
post: | |
description: | | |
This endpoint give ability to register a new user using minimal set of required fields | |
produces: | |
- application/json | |
parameters: | |
- | |
name: common_name | |
in: query | |
description: User's Name and Surname | |
required: true | |
type: string | |
- | |
name: email | |
in: query | |
description: email of the user | |
required: true | |
type: string | |
- | |
name: password | |
in: query | |
description: password | |
required: true | |
type: string | |
- | |
name: password_confirmation | |
in: query | |
description: password confirmation | |
required: true | |
type: string | |
responses: | |
200: | |
description: Successful response | |
schema: | |
type: object | |
properties: | |
success: | |
type: boolean | |
default: true | |
tags: | |
- User | |
/users/password_reset: | |
x-swagger-router-controller: mock | |
post: | |
consumes: | |
- application/json | |
description: | | |
Send reset password email to the user | |
produces: | |
- application/josn | |
parameters: | |
- | |
name: password_reset | |
in: body | |
description: Email of the user | |
required: true | |
schema: | |
type: object | |
required: | |
properties: | |
email: | |
type: string | |
format: email | |
tags: | |
- User | |
responses: | |
204: | |
description: Always responds with 204 code | |
/feedback_items: | |
post: | |
description: | | |
This is the first request that should be done before place any feedback. This endpoint register product and expects unique identifier of the product as an UUID V4. | |
`widget_configuration_uuid` - is a mandatory field, it is received during widget configuration retrieving. | |
`url` - is required to track the page where the product can be found | |
This operation is upsert operation and it should be done every time as the first request. | |
produces: | |
- application/json | |
tags: | |
- Topic | |
- FeedbackItem | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: widget_configuration_uuid | |
in: query | |
description: UUID of the widget configuration | |
required: true | |
type: string | |
format: uuid | |
- | |
name: feedback_item_uuid | |
in: query | |
description: UUID of the product | |
required: true | |
type: string | |
format: uuid | |
- | |
name: name | |
in: query | |
description: Convenient name of product | |
required: true | |
type: string | |
- | |
name: url | |
in: query | |
description: URL where the product may be found | |
required: true | |
type: string | |
responses: | |
200: | |
description: Succssful response | |
schema: | |
$ref: '#/definitions/FeedbackItem' | |
/feedback_items/{uuid}/feedbacks: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
Request all feedbacks by product UUID | |
produces: | |
- application/json | |
parameters: | |
- | |
name: uuid | |
in: path | |
description: UUID of the feedback item | |
required: true | |
type: string | |
format: uuid | |
- | |
name: rating | |
in: query | |
description: filter topics by rating value | |
required: false | |
type: integer | |
minimum: 1 | |
maximum: 5 | |
- $ref: "#/parameters/OrderDirParameter" | |
- $ref: "#/parameters/OrderByParameter" | |
tags: | |
- Topic | |
- FeedbackItem | |
responses: | |
200: | |
description: Succssful response | |
schema: | |
$ref: '#/definitions/TopicsResponse' | |
post: | |
description: | | |
Create Feedback for particular FeedbackItem (Product) | |
produces: | |
- application/json | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: uuid | |
in: path | |
description: UUID of the feedback item | |
required: true | |
type: string | |
format: uuid | |
- | |
name: title | |
required: true | |
in: query | |
type: string | |
format: string | |
- | |
name: body | |
required: true | |
in: query | |
type: string | |
format: string | |
- | |
name: rating | |
required: false | |
in: query | |
type: integer | |
minimum: 1 | |
maximum: 5 | |
tags: | |
- Topic | |
- FeedbackItem | |
responses: | |
200: | |
description: Succssful response | |
schema: | |
$ref: '#/definitions/Topic' | |
/feedback_items/{uuid}/statistic: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
This endpoint returns number of feedbacks grouped by its rating. Additionaly it returns average rating across all feedbacks. | |
produces: | |
- application/json | |
parameters: | |
- | |
name: uuid | |
in: path | |
description: UUID of the feedback item | |
required: true | |
type: string | |
format: uuid | |
tags: | |
- Topic | |
- FeedbackItem | |
responses: | |
200: | |
description: Succssful response | |
schema: | |
$ref: '#/definitions/FeedbackItemStatisticResponse' | |
/topics: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
##### /!\ Deprecated endpoint | |
This endpoint returns topics without any relation to the any subject | |
produces: | |
- application/json | |
tags: | |
- Topic | |
responses: | |
200: | |
description: Successful response | |
schema: | |
$ref: '#/definitions/TopicsResponse' | |
post: | |
description: | | |
##### /!\ Deprecated endpoint | |
Create a new topic | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: title | |
required: true | |
in: query | |
type: string | |
format: string | |
- | |
name: body | |
required: true | |
in: query | |
type: string | |
format: string | |
- | |
name: rating | |
required: false | |
in: query | |
type: integer | |
minimum: 1 | |
maximum: 5 | |
produces: | |
- application/json | |
tags: | |
- Topic | |
responses: | |
200: | |
description: Successful response | |
schema: | |
$ref: '#/definitions/Topic' | |
/topics/{id}: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
This endpoint returns topic by its internal ID | |
##### /!\ In next versions it will accepts only UUID | |
parameters: | |
- | |
name: id | |
required: true | |
in: path | |
type: string | |
format: string | |
produces: | |
- application/json | |
tags: | |
- Topic | |
responses: | |
200: | |
description: Successful response | |
schema: | |
$ref: '#/definitions/Topic' | |
/topics/{topic_id}/answers: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
Queries answers and comments. Returns an object with an array list of answers and an integer total_count with the total number of matching answers and comments. The number of items in the list array is limited to 10. | |
##### /!\ In next versions, this endpoint will accept the only UUID as identifier of the topic | |
parameters: | |
- | |
name: topic_id | |
required: true | |
in: path | |
type: string | |
format: string | |
- | |
name: page | |
description: Specifies the portion of list data. The default value is 1, retrieving activities 0 to 9 (if existing). | |
required: false | |
in: query | |
type: integer | |
- $ref: "#/parameters/OrderDirParameter" | |
- $ref: "#/parameters/OrderByParameter" | |
produces: | |
- application/json | |
tags: | |
- Answers | |
responses: | |
200: | |
description: Successful response | |
schema: | |
"$ref": '#/definitions/Answers' | |
post: | |
description: | | |
Create new Answer for Feedback | |
##### /!\ In next versions, this endpoint will accept the only UUID as identifier of the topic | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: topic_id | |
required: true | |
in: path | |
type: string | |
format: string | |
- | |
name: body | |
required: true | |
in: query | |
type: string | |
format: string | |
produces: | |
- application/json | |
tags: | |
- Answers | |
responses: | |
200: | |
description: Successful response | |
schema: | |
"$ref": '#/definitions/Answers' | |
/topics/{topic_id}/votes: | |
x-swagger-router-controller: mock | |
post: | |
description: | | |
Vote for a topic | |
##### /!\ In next versions, this endpoint will accept the only UUID as identifier of the topic | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: topic_id | |
required: true | |
in: path | |
type: string | |
format: string | |
produces: | |
- application/json | |
tags: | |
- Topic | |
- Vote | |
responses: | |
200: | |
description: Successful response | |
schema: | |
"$ref": '#/definitions/Vote' | |
/answers/{uuid}/votes: | |
x-swagger-router-controller: mock | |
get: | |
description: | | |
Votes for answers | |
this only accepts UUID | |
parameters: | |
- | |
name: uuid | |
required: true | |
in: path | |
type: string | |
format: string | |
tags: | |
- Answers | |
- Vote | |
responses: | |
200: | |
description: Successful response | |
schema: | |
"$ref": '#/definitions/Votes' | |
/answers/{id}/vote: | |
x-swagger-router-controller: mock | |
post: | |
description: | | |
Vote for the answer | |
parameters: | |
- $ref: "#/parameters/X-User-Token" | |
- | |
name: id | |
required: true | |
in: path | |
type: integer | |
produces: | |
- application/json | |
tags: | |
- Vote | |
- Answers | |
responses: | |
200: | |
description: Successful response | |
schema: | |
"$ref": '#/definitions/Vote' | |
/swagger: | |
x-swagger-pipe: swagger_raw | |
parameters: | |
X-User-Token: | |
name: X-User-Token | |
description: access token of the user's session | |
type: string | |
required: true | |
in: header | |
OrderDirParameter: | |
name: order_dir | |
in: query | |
description: Direction of the sorting. The default direction is `desc` | |
default: desc | |
required: false | |
type: string | |
OrderByParameter: | |
name: order_by | |
in: query | |
description: The field by which sort the results. The default field is `created_at` | |
default: created_at | |
required: false | |
type: string | |
enum: | |
- created_at | |
- updated_at | |
- rating | |
definitions: | |
User: | |
allOf: | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- $ref: '#/definitions/ModelWithID' | |
- type: object | |
description: User | |
required: | |
- name | |
- username | |
properties: | |
name: | |
type: string | |
description: This is basically the display-name of the user on the platform. It returns the username if it is defined, common_name otherwise. | |
default: John | |
username: | |
type: string | |
description: An unique alias of the user. The default value is an empty string. | |
default: John | |
common_name: | |
type: string | |
description: The real name of the user. Required. | |
about_me: | |
type: string | |
description: A short text where the user describes himself. The default value is null. | |
default: I'm the choosen one | |
gamification: | |
$ref: '#/definitions/Gamification' | |
total_posts: | |
type: integer | |
description: Total number of posts made by user | |
profile_images: | |
$ref: '#/definitions/ProfileImages' | |
wallpapers: | |
$ref: '#/definitions/Wallpapers' | |
created_at: | |
type: string | |
description: The date and time when the user was created, in ISO 8601 format. | |
updated_at: | |
type: string | |
description: The date and time when the user data was last updated, in ISO 8601 format. If the user data was never updated, the value is identical to created_at. | |
url: | |
type: string | |
description: The full URL of the user page. Per default it is https://your.domain/users/name where "name" is the URL-encoded name. | |
UserStatistic: | |
type: object | |
description: Overview of user's activity | |
required: | |
- feedbacks | |
- answers | |
- votes | |
properties: | |
feedbacks: | |
type: object | |
required: | |
- total_count | |
- list | |
properties: | |
total_count: | |
description: Total number of feedbacks that user left | |
type: integer | |
list: | |
type: array | |
items: | |
$ref: '#/definitions/Topic' | |
answers: | |
type: object | |
required: | |
- total_count | |
- list | |
properties: | |
total_count: | |
description: Total number of feedbacks that user left | |
type: integer | |
list: | |
type: array | |
items: | |
$ref: '#/definitions/Answer' | |
votes: | |
type: object | |
required: | |
- total_count | |
- list | |
properties: | |
total_count: | |
description: Total number of feedbacks that user left | |
type: integer | |
list: | |
type: array | |
items: | |
$ref: '#/definitions/Vote' | |
Gamification: | |
type: object | |
description: An object containing the gamification details of the user | |
required: | |
- level | |
- scope | |
properties: | |
level: | |
type: integer | |
description: An integer representing the current experience level of the user based on his score. | |
minimum: 0 | |
maximum: 5 | |
scope: | |
type: number | |
description: The sum of all points gathered through different actions like posting a new topic or receiving a vote on ones answer. Different actions yield different (configurable) amounts of points. | |
minimum: 0 | |
maximum: 5 | |
FeedbackItem: | |
allOf: | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- $ref: '#/definitions/ModelWithUUID' | |
- type: object | |
required: | |
- name | |
- url | |
- feedbacks | |
- statistic | |
properties: | |
feedbacks: | |
type: array | |
items: | |
$ref: '#/definitions/Topic' | |
name: | |
type: string | |
description: Name of the item been reviewed | |
url: | |
type: string | |
description: Page where the product can be found | |
statistic: | |
type: object | |
properties: | |
5: | |
description: Number of feedbacks with rating of 5 | |
type: integer | |
minimum: 0 | |
4: | |
description: Number of feedbacks with rating of 4 | |
type: integer | |
minimum: 0 | |
3: | |
description: Number of feedbacks with rating of 3 | |
type: integer | |
minimum: 0 | |
2: | |
description: Number of feedbacks with rating of 2 | |
type: integer | |
minimum: 0 | |
1: | |
description: Number of feedbacks with rating of 1 | |
type: integer | |
minimum: 0 | |
Topic: | |
allOf: | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- $ref: '#/definitions/ModelWithID' | |
- type: object | |
required: | |
- title | |
- body | |
- rating | |
- status | |
- author | |
properties: | |
type: | |
type: string | |
description: The content type of the topic. Possible values are Question, Feedback, Tutorial, Article, and Faq. | |
title: | |
type: string | |
description: The title text of the topic. | |
body: | |
type: string | |
description: "The body text of the topic. It may contain some basic HTML, restricted to the following tags: p, br, blockquote, ol, ul, li, a (including attributes href, title, target), em, i, strong, b." | |
default: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent nec purus dui. Nulla quis lectus iaculis, porttitor est sit amet, cursus lectus. Aenean ac tortor vel arcu rutrum blandit | |
author: | |
$ref: '#/definitions/User' | |
mood: | |
type: integer | |
description: A number representing the mood of the user who created the topic. Higher numbers mean better mood. By default, numbers from 1 to 4 are supported and displayed in the form of smileys. The default value is null. | |
rating: | |
type: integer | |
description: "This attribute is not related to Rating. The attribute is only relevant for topics of the type Feedback. The number represents the author's rating of the issue he is giving feedback for. Higher numbers mean better rating. Per default, numbers from 1 to 5 are supported and displayed in the form of smileys. The default value is 5." | |
url: | |
type: string | |
description: "The full URL of the topic." | |
tags: | |
type: array | |
items: | |
$ref: '#/definitions/Tag' | |
status: | |
type: string | |
description: Status of the Feedback | |
default: fresh | |
enum: | |
- fresh | |
- discussed | |
- answered | |
- closed | |
- faq | |
Answer: | |
allOf: | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- $ref: '#/definitions/ModelWithID' | |
- type: object | |
required: | |
- body | |
- author | |
- private | |
- mood | |
properties: | |
body: | |
type: string | |
description: "The body text of the answer. It may contain some basic HTML, restricted to the following tags: p, br, blockquote, ol, ul, li, a (including attributes href, title, target), em, i, strong, b." | |
default: Shall I compare thee to a summer’s day? | |
author: | |
$ref: '#/definitions/User' | |
answerable_id: | |
type: integer | |
minimum: 1 | |
description: The unique identifier of the answered item. | |
answerable_type: | |
type: string | |
description: The type of the answered item. Currently limited to Topic. | |
default: 'Feedback' | |
private: | |
type: boolean | |
description: "The answer will only be accessible to agents and the user who posted it" | |
default: false | |
solution: | |
type: boolean | |
description: "True, if the answer is the accepted solution to the question. Only applicable if the answerable_type is a topic of the type Question" | |
default: false | |
mood: | |
type: integer | |
minimum: 0 | |
maximum: 5 | |
description: "A number representing the mood of the answering user. Higher numbers mean better mood. Per default, numbers from 1 to 4 are supported and presented in the form of smileys." | |
rating: | |
type: integer | |
minimum: 0 | |
description: "Deprecated, will be removed." | |
recent_report_id: | |
type: integer | |
minimum: 1 | |
description: "The unique identifier of the last report filed by users about the current answer. Will only be accessible to team members. The default value is null." | |
attachments: | |
type: array | |
description: "An array of IDs of Assets. The default value is an empty array." | |
items: | |
$ref: '#/definitions/Assets' | |
statistics: | |
$ref: '#/definitions/Statistic' | |
Answers: | |
type: object | |
required: | |
- total_count | |
- list | |
properties: | |
total_count: | |
type: integer | |
maximum: 5 | |
minimum: 0 | |
list: | |
type: array | |
minItems: 3 | |
maxItems: 5 | |
items: | |
$ref: '#/definitions/Answer' | |
TopicsResponse: | |
type: object | |
required: | |
- total_count | |
- list | |
properties: | |
total_count: | |
type: integer | |
maximum: 5 | |
minimum: 0 | |
list: | |
type: array | |
minItems: 3 | |
maxItems: 5 | |
items: | |
$ref: '#/definitions/Topic' | |
AssetVariant: | |
type: object | |
required: | |
- width | |
- height | |
- url | |
properties: | |
width: | |
type: integer | |
minimum: 10 | |
maximum: 400 | |
description: An Integer representing the asset variant width in pixels | |
height: | |
type: integer | |
minimum: 10 | |
maximum: 400 | |
description: An Integer representing the asset variant height in pixels | |
url: | |
type: string | |
description: A String representing the file path, relative to the site root (i.e. starting with a slash). | |
Asset: | |
allOf: | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- $ref: '#/definitions/ModelWithID' | |
- type: object | |
required: | |
- type | |
- title | |
- variants | |
- file | |
properties: | |
type: | |
type: string | |
description: The type of the asset. Possible values are Image, Document, and Link. | |
default: Image | |
title: | |
type: string | |
description: The title text of the asset | |
default: '' | |
description: | |
type: string | |
description: The description text of the asset | |
default: '' | |
uploader: | |
$ref: '#/definitions/User' | |
variants: | |
properties: | |
small: | |
$ref: '#/definitions/AssetVariant' | |
medium: | |
$ref: '#/definitions/AssetVariant' | |
large: | |
$ref: '#/definitions/AssetVariant' | |
file: | |
type: string | |
description: The path of the file, relative to the site root (i.e. starting with a slash). | |
Assets: | |
type: array | |
description: An asset is an image, a document, or a link and can be attached to a topic, an answer and other objects. An asset object does not contain binary data, but references them by URL. | |
items: | |
$ref: '#/definitions/Asset' | |
ProfileImages: | |
type: array | |
description: An array of image assets that are displayed as profile images. The default value is an empty array. | |
items: | |
$ref: '#/definitions/Asset' | |
Wallpapers: | |
type: array | |
description: An array of image assets that are displayed as background image. The default value is an empty array. | |
items: | |
$ref: '#/definitions/Asset' | |
Tag: | |
type: object | |
description: "TODO" | |
Statistic: | |
type: object | |
properties: | |
vote_count: | |
type: number | |
description: to be done | |
default: 0 | |
Vote: | |
allOf: | |
- $ref: '#/definitions/ModelWithID' | |
- $ref: '#/definitions/ModelWithTimestamps' | |
- type: object | |
required: | |
- votable_type | |
- votable_id | |
- votable | |
- user | |
properties: | |
votable_type: | |
type: string | |
description: Name of the object that was voted | |
votable_id: | |
type: integer | |
description: id of the object that was voted | |
votable: | |
$ref: '#/definitions/Topic' | |
user: | |
$ref: '#/definitions/User' | |
Votes: | |
type: array | |
items: | |
$ref: '#/definitions/Vote' | |
ModelWithTimestamps: | |
type: object | |
required: | |
- created_at | |
- updated_at | |
properties: | |
created_at: | |
type: string | |
format: date-time | |
description: "The date and time when the answer was posted, in ISO 8601 format." | |
updated_at: | |
type: string | |
format: date-time | |
description: "The date and time when the answer was last updated, in ISO 8601 format. If the answer was never updated, the value is identical to created_at." | |
ModelWithID: | |
type: object | |
required: | |
- id | |
properties: | |
id: | |
type: integer | |
description: The unique identifier | |
minimum: 1 | |
maximum: 999999 | |
ModelWithUUID: | |
type: object | |
required: | |
- uuid | |
properties: | |
uuid: | |
type: string | |
description: The unique identifier | |
format: uuid | |
FeedbackItemStatisticResponse: | |
type: object | |
required: | |
- average | |
- "5" | |
- "4" | |
- "3" | |
- "2" | |
- "1" | |
properties: | |
average: | |
type: number | |
description: Average rating of the FeedbackItem | |
"5": | |
type: integer | |
description: Number of feedbacks with grade 5 | |
"4": | |
type: integer | |
description: Number of feedbacks with grade 4 | |
"3": | |
type: integer | |
description: Number of feedbacks with grade 3 | |
"2": | |
type: integer | |
description: Number of feedbacks with grade 2 | |
"1": | |
type: integer | |
description: Number of feedbacks with grade 1 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment