---
# System prepended metadata

title: faq spec notes
tags: [Spec]

---

###### tags: `Spec`

# faq spec notes

## Proposal for API

**Base Path**: `/faq`

| Path | Task                                                     |
| ------------------------ | ------------------------------------ |
| `/tags`                  | returns all available tag names and whether priortity flag.<br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, sort is alphabetical ascending without customization.|
| `/tags/questions`        | return a list of filterable questions and corresponding answers for each prioritized tag found. <br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, `sortBy` (={ *hits*, *ID default*, *updatedAt* }), `sortDir`, `search` |
| `/questions`             | return a list of filterable questions and corresponding answers. <br><br> **Parameters:** `filter`, `offset`, `limit`, `Accept-Language`, `sortBy` (={ *hits*, *ID default*, *updatedAt* }), `sortDir`, `search` |
| `/questions/{id}/{var}`  | post statistical values to the server.<br><br>{var} := { *hit*, *like*, *(helpful)Vote*, }<br><br>**Paramaters:** `id`, in case of user related feedback: `uuid` |

## Proposal with multiple 'primary' tags - BE voted for this

```plantuml
@startuml

skinparam linetype ortho
skinparam nodesep 40
skinparam ranksep 40
skinparam monochrome true
skinparam shadowing false
skinparam dpi 300

skinparam StereotypeEBackgroundColor white

entity "faq_questions" as questions {
	*id: int32 <<generated>>
	--
	question_de: varchar(512)
	question_en: varchar(512)
	answer_de: text
	answer_en: text
	hit_count: int32
	color_id: tinyint unsigned
	persistent: boolean
}

entity "faq_tags" as tags {
	*id: int32 <<generated>>
	--
	name_de: varchar(512)
	name_en: varchar(512)
	*is_priority: boolean
}

entity "faq_reactions" as reactions {
	*id: int32 <<generated>>
	--
	uuid: uuid
	faq_question_id: int unsigned
	helpful: tinyint(1)
}

entity "colors" {
	*id: tinyint unsigned <<generated>>
	--
	name: varchar(64)
}

colors ||-r-o{ questions
questions }o--o{ tags
questions ||--o{ reactions

' note right on tags::isPriority: "Hello World"

note right of questions::persistent
  This flag indicates if this
  question should be updated
  /deleted/created by the importer.
end note

note as priority_note
  This flag indicates if this
  tag is one of the "priority"-tags.
  These tags are "browsable".
end note
tags::is_priority .. priority_note

note as helpful_note
  This flag indicates if this reaction should
  be interpreted as helpful (1) or not helpful (-1).
  <i>Allowed values: -1,1</i>
  We use tinyint (not boolean) so that we
  can sum all values up to get the helpful rate.
end note
reactions::helpful .. helpful_note

@enduml
```

## cheatsheet

| Type          | Symbol    |
| ------------- | --------- |
| Zero or One   | `|o--`    |
| Exactly One   | `||--`    |
| Zero or Many  | `}o--`    |
| One or Many   | `}|--`    |
| layout        | `right, left, up, down` or `r, l, u, d` |




## Proposal with single 'primary' tags

```plantuml
@startuml

' skinparam linetype ortho
skinparam nodesep 40
skinparam ranksep 40
skinparam monochrome true
skinparam shadowing false
skinparam dpi 300

skinparam StereotypeEBackgroundColor white

entity "faq_questions" as questions {
	*id: int32 <<generated>>
	--
	*primary_tag_id: int32 <<FK>>
	question_de: varchar(512)
	question_en: varchar(512)
	answer_de: text
	answer_en: text
	hit_count: int32
}

entity "faq_tags" as tags {
	*id: int32 <<generated>>
	--
	name_de: varchar(512)
	name_en: varchar(512)
	*can_primary: boolean
}

questions }o-right-|| tags : relation for primary tag
questions }o--o{ tags : relation for secondary tags

note "This flag indicates if this\ntag should be choosable\nas primary tag" as can_primary_note

tags::can_primary .. can_primary_note

@enduml
```