API Design

Genereller Aufbau

/api/:kind/:version/:domainName/:commandName

Examples:
/api/query/v1/items/getList
/api/query/v1/tags/getList

/api/command/v1/item/submit
/api/command/v1/item/suggestChange

API Design

Ist im Google Drive in einem Google Sheets

Query API Design

Route	Query	Response OK
/api/query/v1/items/list	{ page?: number = 1 // Has to start with 1 not 0 limit?: number = 16 sort?: string = relevance (relevance, lightest, heaviest) query?: string = "" // Search string e.g.: "Apple iPhone" in name and tags fields tags?: string[] // Show only items with these tags included slug?: string }	{ total: number page: number limit: number data: Item[] }
/api/query/v1/items/related	{ page?: number = 1 // Has to start with 1 not 0 limit?: number = 16 // Count of items for related items slug: string }	{ total: number page: number limit: number data: Item[] }
/api/query/v1/items/statistics	{ query?: string = "" // Search string e.g.: "Apple iPhone" in name and tags fields tags?: string[] // Show only items with these tags included }	{ heaviest: Item lightest: Item averageWeight: number // in Gramm }
/api/query/v1/tags/list	{ page?: number = 1 // Has to start with 1 not 0 limit?: number = 16 sort?: string = relevance (asc, desc, most-used) }	{ total: number page: number limit: number data: Tag[] }
/api/query/v1/tags/related	{ page?: number = 1 // Has to start with 1 not 0 limit?: number = 16 query?: string = "" // Search string e.g.: "Apple iPhone" in name and tags fields tags?: string[] // Show only items with these tags included }	{
total: number
page: number
limit: number
data: Tag[]
}

Command API Design

Route	Body	Response OK
/api/command/v1/items/insert	{ name: string weight: { value: number aditionalValue?: number isCa?: number } source?: string image?: string // URL to image tags?: string[] }
/api/command/v1/items/suggest	{ name?: string weight: { value?: number aditionalValue?: number isCa?: number } source?: string image?: string // URL to image tags?: string[] }

Entities

Item	{ "id": "0ab3fd6f-aa90-4b1f-a6b3-fdd17a3a3947", "name": "Tesla Model 3", "slug": "tesla-model-3", "weight": { "value": 1825, "aditionalValue": 2000, /** Optional / "isCa": false / In Gramm and 1e10 / }, "source": "https://wikipedia.org/wiki/Tesla_Model_3", /* Optional / "image": "https://via.placeholder.com/350x150", /* URL to image Optional */ "tags": [{ // Other Issue "name":"Tesla Model 3", "slug":"tesla-model-3", "count": 345 }], "user": "arnorld doofenschmirtz" }
Tag	{ "name":"Tesla Model 3", "slug":"tesla-model-3", "count": 345 }