Skip to content

API reference

Jump to bottom
Armandas edited this page Oct 16, 2023 · 14 revisions

Museum app API reference

Here you can reference how to use a specific API route from museum app.

Museum

GET /museums Get a list of museums

GET museums

Returns a list of museums and if there is a next page.

Query parameters

name type data type description
page optional number Page number (page ∈ ℕ)
pageSize optional number Amount of museums per page (pageSize ∈ ℕ ∩ [5,30])

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "museums": [
        {
            "id": 8,
            "name": "Uffizi Gallery",
            "description": "Uffizi Gallery",
            "imageUrl": null
        },
        {
            "id": 9,
            "name": "The Metropolitan Museum of Art",
            "description": "The Metropolitan Museum of Art",
            "imageUrl": null
        },
        {
            "id": 14,
            "name": "ggasg",
            "description": "gasgs",
            "imageUrl": null
        },
        {
            "id": 15,
            "name": "ggasg",
            "description": "gasgs",
            "imageUrl": null
        },
        {
            "id": 16,
            "name": "ggasg",
            "description": "gasgs",
            "imageUrl": null
        }
    ],
    "hasNext": true
}
422 application/json 
{
    "errors": [
        {
            "field": "page",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/v1/museums?page=2&pageSize=5'
GET /museums/:museumId Get a single museum

GET a museum

Parameters

name type data type description
museumId required number The id of the museum

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "museum": {
        "id": 7,
        "name": "Rijksmuseum",
        "description": "Rijksmuseum",
        "imageUrl": null
    }
}
404 application/json 
{
    "errors": [
        "Museum not found"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "museumId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/v1/museums/1'
POST /museums Create a new museum (ADMIN)
USER MUST BE AN ADMIN

POST create a new museum

Headers

name type data type description
Authorization required string Token must be a bearer token

JSON body parameters

name type data type description
name required string Title of the museum
description required string Description of the museum

Responses

HTTP Code Content-Type Response
201 application/json 
{
    "museum": {
        "id": 20,
        "name": "MusMus4",
        "description": "Museum description very large building lots and lots of items and categories",
        "imageUrl": null
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "name",
            "message": "Required"
        }
    ]
}

Example cURL

 curl --location 'http://localhost:4000/api/v1/museums' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIbzI1NiJ9.ey...gS_kLNb1Cdaujo' \
--data '{
    "name": "MusMus4",
    "description": "Museum description very large building lots and lots of items and categories"
}'
PUT /museums/:museumId Update museum data (ADMIN)
USER MUST BE AN ADMIN

PUT update museum data

Updates museum values in database and returns an object with the updated values.

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum

JSON body parameters

name type data type description
name required string Title of the museum
description required string Description of the museum

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "museum": {
        "id": 6,
        "name": "Museum22",
        "description": "Some changed lorem ipsum whatever it means in latin and thats it",
        "imageUrl": null
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "Museum not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "name",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location --request PUT 'http://localhost:4000/api/v1/museums/64' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIbzI1NiJ9.ey...gS_kLNb1Cdaujo' \
--data '{
    "name": "Museum22",
    "description": "Some changed lorem ipsum whatever it means in latin and thats it"
}'
DELETE /museums/:museumId Delete a museum (ADMIN)
USER MUST BE AN ADMIN

DELETE a museum

Deletes a museum and all categories and items within those categories.

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum

Responses

HTTP Code Content-Type Response
204
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "Museum not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "museumId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location --request DELETE 'http://localhost:4000/api/v1/museums/18' \
--header 'Authorization: Bearer eyJhbGciOiJIbzI1NiJ9.ey...gS_kLNb1Cdaujo'

Categories

GET /museums/:museumId/categories Get a list of museum categories

GET museum categories

Query parameters

name type data type description
page optional number Page number (page ∈ ℕ)
pageSize optional number Amount of categories per page (pageSize ∈ ℕ ∩ [5,30])

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "categories": [
        {
            "id": 15,
            "createdAt": "2023-09-28T18:13:36.121Z",
            "name": "fffg",
            "description": "ffgsg",
            "museumId": 1,
            "imageUrl": null
        },
        {
            "id": 16,
            "createdAt": "2023-09-28T18:13:37.374Z",
            "name": "fffg",
            "description": "ffgsg",
            "museumId": 1,
            "imageUrl": null
        },
        {
            "id": 17,
            "createdAt": "2023-09-28T18:13:38.465Z",
            "name": "fffg",
            "description": "ffgsg",
            "museumId": 1,
            "imageUrl": null
        },
        {
            "id": 18,
            "createdAt": "2023-09-28T18:13:39.564Z",
            "name": "fffg",
            "description": "ffgsg",
            "museumId": 1,
            "imageUrl": null
        },
        {
            "id": 20,
            "createdAt": "2023-09-28T18:13:41.692Z",
            "name": "fffg",
            "description": "ffgsg",
            "museumId": 1,
            "imageUrl": null
        }
    ],
    "hasNext": true
}
422 application/json 
{
    "errors": [
        {
            "field": "page",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/v1/museums/1/categories?page=1&pageSize=10'
GET /museums/:museumId/categories/:categoryId Get a single category

GET a category

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "category": {
        "id": 30,
        "createdAt": "2023-10-15T19:15:15.003Z",
        "name": "Paintings",
        "description": "Until recently, the prevailing view assumed lorem ipsum was born as a nonsense text.",
        "museumId": 7,
        "imageUrl": null,
        "museum": {
            "name": "Rijksmuseum"
        }
    },
    "canEdit": false
}
404 application/json 
{
    "errors": [
        "Category not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "categoryId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location --request GET 'http://localhost:4000/api/v1/museums/7/categories/30'
POST /museums/:museumId/categories Create a new category(ADMIN)
USER MUST BE AN ADMIN

POST create a new category

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum

JSON body parameters

name type data type description
name required string Title of the category
description required string Description of the category

Responses

HTTP Code Content-Type Response
201 application/json 
{
    "category": {
        "id": 31,
        "createdAt": "2023-10-15T19:27:02.734Z",
        "name": "Description about the sculptures category",
        "description": "Sculptures",
        "museumId": 1,
        "imageUrl": null
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "name",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location --request POST 'http://localhost:4000/api/v1/museums/1/categories' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI...t9CJfajntlpL3WRzd4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "Sculptures",
    "name": "Description about the sculptures category"
}'
PUT /museums/:museumId/categories/:categoryId Update category data (ADMIN)
USER MUST BE AN ADMIN

PUT update category data

Updates museum values in database and returns an object with the updated values.

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category

JSON body parameters

name type data type description
name required string Title of the category
description required string Description of the category
museumId optional number The id of a museum you want to move this category to

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "category": {
        "id": 32,
        "createdAt": "2023-10-15T19:31:08.794Z",
        "name": "Sculptures2",
        "description": "Sculptures from 91th century.",
        "museumId": 2,
        "imageUrl": null
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "Category not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "name",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location --request PUT 'http://localhost:4000/api/v1/museums/1/categories/32' \
--header 'Authorization: Bearer eyJhbGciOi...ntlpL3WRzd4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "Sculptures from 91th century.",
    "name": "Sculptures2",
    "museumId": 2
}'
DELETE /museums/:museumId/categories/:categoryId Delete a category(ADMIN)
USER MUST BE AN ADMIN

DELETE a category

Deletes the category and all the items in it.

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category

Responses

HTTP Code Content-Type Response
204
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "Category not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "categoryId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location --request DELETE 'http://localhost:4000/api/v1/museums/2/categories/32' \
--header 'Authorization: Bearer eyJhbGciOiJ...jntlpL3WRzd4'

Items

GET /museums/:museumId/categories/:categoryId/items Get a list of museum category items

GET museum category items

Query parameters

name type data type description
page optional number Page number (page ∈ ℕ)
pageSize optional number Amount of items per page (pageSize ∈ ℕ ∩ [5,30])

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "items": [
        {
            "id": 35,
            "title": "painting1",
            "description": "This is an incredible painting",
            "imageUrl": null,
            "categoryId": 30
        },
        {
            "id": 36,
            "title": "painting2",
            "description": "This is an incredible painting2",
            "imageUrl": null,
            "categoryId": 30
        },
        {
            "id": 37,
            "title": "painting3",
            "description": "This is an incredible painting3",
            "imageUrl": null,
            "categoryId": 30
        }
    ],
    "hasNext": false
}
422 application/json 
{
    "errors": [
        {
            "field": "page",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location --request GET 'http://localhost:4000/api/v1/museums/7/categories/30/items'
GET /museums/:museumId/categories/:categoryId/items/itemId Get a single item

GET an item

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category
itemId required number The id of the item

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "item": {
        "id": 35,
        "title": "painting1",
        "description": "This is an incredible painting",
        "imageUrl": null,
        "categoryId": 30,
        "Category": {
            "id": 30,
            "createdAt": "2023-10-15T19:15:15.003Z",
            "name": "Paintings",
            "description": "Until recently, the prevailing view assumed lorem ipsum was born as a nonsense text.",
            "museumId": 7,
            "imageUrl": null,
            "museum": {
                "name": "Rijksmuseum",
                "id": 7
            }
        }
    }
}
404 application/json 
{
    "errors": [
        "Item not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "itemId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/v1/museums/7/categories/30/items/35'
POST /museums/:museumId/categories/:categoryId/items Create a new item

POST create a new item in a category

New items can only be created by users who have Curator role and has access to the category assigned by the Admin. Or can be created by the Admin

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category

JSON body parameters

name type data type description
title required string Title of the item
description required string Description of the item

Responses

HTTP Code Content-Type Response
201 application/json 
{
    "item": {
        "id": 38,
        "title": "Alexander Calder",
        "description": "This is my description3",
        "imageUrl": null,
        "categoryId": 30
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "title",
            "message": "Required"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/v1/museums/7/categories/30/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOi...NiZ2CmDRN5QO4' \
--data '{
    "title": "Alexander Calder",
    "description": "This is my description3"
}'
PUT /museums/:museumId/categories/:categoryId/items/:itemId Update item data

PUT update item data

Items can only be updated by users who have Curator role and has access to the category assigned by the Admin. Or can be updated by the Admin

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category
itemId required number The id of the item

JSON body parameters

name type data type description
title required string Title of the item
description required string Description of the item
newCategoryId optional number Change item category. The category must exist and curator must have editing access to the category where the item will be moved.

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "item": {
        "id": 35,
        "title": "new Title",
        "description": "new Description!",
        "imageUrl": null,
        "categoryId": 31
    }
}
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "New category doesn't exists"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "title",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location --request PUT 'http://localhost:4000/api/v1/museums/7/categories/30/items/35' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOi...ZMuZ7ENiZ2CmDRN5QO4' \
--data '{
    "title": "new Title",
    "description": "new Description!",
    "newCategoryId": 31
}'
DELETE /museums/:museumId/categories/:categoryId/items/:itemId Delete an item

DELETE an item

Items can only be deleted by users who have Curator role and has access to the category assigned by the Admin. Or can be deleted by the Admin

Headers

name type data type description
Authorization required string Token must be a bearer token

Parameters

name type data type description
museumId required number The id of the museum
categoryId required number The id of the category
itemId required number The id of the item

Responses

HTTP Code Content-Type Response
204
401 application/json 
{
    "errors": [
        "Invalid access token"
    ]
}
404 application/json 
{
    "errors": [
        "Item not found!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "itemId",
            "message": "Expected number, received nan"
        }
    ]
}

Example cURL

curl --location --request DELETE 'http://localhost:4000/api/v1/museums/7/categories/30/items/36' \
--header 'Authorization: Bearer eyJhbGciOi...ZMuZ7ENiZ2CmDRN5QO4'

Auth

POST /auth/register Register a new user

POST register a new user

Registers a new user.

JSON body parameters

name type data type description
name required string User name
surname required string User surname
email required string User email
password required string User password

Responses

HTTP Code Content-Type Response
201 application/json
409 application/json 
{
    "errors": [
        "user with that email already exists!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "email",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/auth/register' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Sterling",
    "surname": "Falcon",
    "email": "[email protected]",
    "password": "Sterling1"
}'
POST /auth/login Login with credentials

POST Login with credentials

Tries to login user with passed credentials. Returns access and refresh tokens on success.

JSON body parameters

name type data type description
email required string User email
password required string User password

Responses

HTTP Code Content-Type Response
200 application/json 
{
    "accessToken": "eyJhbGciOiJIU...uyqhlN-8XY9d_-Y",
    "expiresIn": 7197000,
    "name": "Sterling",
    "surname": "Falcon",
    "email": "[email protected]",
    "role": "GUEST"
}

And refreshToken cookie is in a header
401 application/json 
{
    "errors": [
        "email or password is incorrect!"
    ]
}
422 application/json 
{
    "errors": [
        {
            "field": "email",
            "message": "Expected string, received null"
        }
    ]
}

Example cURL

curl --location 'http://localhost:4000/api/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[email protected]",
    "password": "Sterling1"
}'
POST /auth/refresh Refresh access token

POST refresh access token

Refreshes access token, invalidates refresh token and return a new refresh token in a header.

Cookies

name type data type description
refreshToken required string Cookie of login refresh token

Responses

HTTP Code Content-Type Response
201 application/json 
{
    "accessToken": "eyJhbGciOiJIUzI...eL9B5zpOE",
    "expiresIn": 7197000
}

And a cookie in a header
403 application/json 
{
    "errors": [
        "Invalid or expired refresh token"
    ]
}
422 application/json 
{
    "errors": [
        "Missing a refresh token!"
    ]
}

Example cURL

curl --location --request POST 'http://localhost:4000/api/auth/refresh' \
--header 'Cookie: refreshToken=eyJhbGciOiJI...YTajKLtWrbz0'
POST /auth/logout Logout the user

PUT logout the user

Invalidates all user refresh tokens.

Headers

name type data type description
Authorization required string Token must be a bearer token

Responses

HTTP Code Content-Type Response
200 text/plain 
OK
403 application/json 
{
    "errors": [
        "Invalid or expired refresh token"
    ]
}
422 application/json 
{
    "errors": [
        "Missing accessToken in headers!"
    ]
}

Example cURL

curl --location --request POST 'http://localhost:4000/api/auth/logout' \
--header 'Authorization: Bearer eyJhbGciOiJI...eMBsoDMk5ng1Lq8bfyKsNU'
Clone this wiki locally