Backend endpoints - adamk90/PictoGraphy GitHub Wiki

Documentation of the endpoints

For testing purposes, an admin user is always added with fix password P!ct0Gr4phy. It can be used to check admin privileges.

Note: all example curl calls use --insecure option, because the SSL certificate is self-signed currently. This could be omitted if 3rd party signed certificate is in use.

Registration

Purpose: registers the user.

Endpoint: POST /api/register

Payload

{ 
   'username': username,
   'password': password,
   'email': email
}

Request requirements:

username should be at least 3 characters long
username should be unique among the database (no duplicate users)
password should be at least 8 characters long
password should contain at least one lowercase letter
password should contain at least one uppercase letter
password should contain at least one number
password should contain at least one special character
email should contain exactly one '@'
email should have prefix before '@'
email should have suffix after '@'
email should be unique among the database (no duplicate emails)

Response

Successful response: 200 OK Successful response body: empty

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request POST 'https://localhost:3000/register' \
--header 'Content-Type: application/json' \
--data-raw '{"username": "test","password": "aaaaaaA1*", "email": "test@test"}' \
--insecure

Example valid response

None.

Login

Purpose: logins the user.

Endpoint: POST /api/login

Payload

{ 
   'username': username,
   'password': password,
}

Request requirements:

username should be already in database
password should match password in database

Response

Successful response: 200 OK Successful response body:

{ 
   'token': JWT token,
   'isAdmin': bool isAdmin,
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request POST 'https://localhost:3000/login' \
--header 'Content-Type: application/json' \
--data-raw '{"username": "test","password": "aaaaaaA1*"}' \
--insecure

Example valid response

{
 "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTYyMDQwLCJleHAiOjE2MDY1NjQ0NDB9.r3zj85Co02nS3PbDzcB-GSkMUoEWyoSJkcB8YW0m5EM",
 "isAdmin":false
}

Upload

Purpose: uploads caff file for user.

Endpoint: POST /api/upload

This endpoint can only be used after authentication, so the request should contain valid JWT token in the Authorization header (as Bearer token).

Payload

The caff file.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
Caff file should be a valid Caff file (parser should parse it successfully)

Response

Successful response: 200 OK Successful response body:

{ 'caff': {
    'id': '...', //<- ObjectId
    'previewBmp': '...',  //<- string path to server static image
    'uploader': '...', //<- string username
    'creator': '...', //<- string
    'creationDate': ..., //<- Date 
    'tags': [
       'tag1', //<- string
       'tag2',
       // ...
    ]
  }
}

Unsuccessful response: 400 BAD

Example valid curl call

/home/adamk/GitProjects/PictoGraphy/CaffParser/testfiles/1.caff part should be changed to point to valid caff file

curl --location --request POST 'https://localhost:3000/api/upload' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTYyMDQwLCJleHAiOjE2MDY1NjQ0NDB9.r3zj85Co02nS3PbDzcB-GSkMUoEWyoSJkcB8YW0m5EM' \
--form 'caff=@"/home/adamk/GitProjects/PictoGraphy/CaffParser/testfiles/1.caff"' \
--insecure

Example valid response

{
  "caff" {
    "id":"5fc235a2639b4f25ea0d32fb",
    "previewBmp":"/images/previews/5fc235a2639b4f25ea0d32fb_preview.bmp",
    "uploader":"test",
    "creator":"Test Creator",
    "creationDate":"2020-07-02T12:50:00.000Z",
    "tags": [
      "landscape",
      "sunset",
      "mountains"
    ]
  }
}

Search caffs

Purpose: search for caff files (or get all).

Endpoint: GET /api/search

This endpoint can only be used after authentication, so the request should contain valid JWT token in the Authorization header (as Bearer token).

Optional query parameters:

should contain searchBy= (currently only supports 'tag' -> searchBy=tag)
should contain q= (which can be a valid regex)
example: /api/search?searchBy=tag&q=land.*

If no (or not valid) query parameters present, it returns all the caffs.

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database

Response

Successful response: 200 OK Successful response body:

{ 
    'caffs': [
        {
            'id': '...', //<- ObjectId
            'previewBmp': '...',  //<- string path to server static image
            'uploader': '...', //<- string username
            'creator': '...', //<- string
            'creationDate': ..., //<- Date 
            'tags': [
               'tag1', //<- string
               'tag2',
               // ...
            ]
        },
        //...
    ]
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/search' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTYyMDQwLCJleHAiOjE2MDY1NjQ0NDB9.r3zj85Co02nS3PbDzcB-GSkMUoEWyoSJkcB8YW0m5EM' \
--insecure

Example valid response

{
    "caffs": [
        {
            "id": "5fc1b5eedd72525c629ec48e",
            "previewBmp": "/images/previews/5fc1b5eedd72525c629ec48e_preview.bmp",
            "uploader": "admin",
            "creator": "Test Creator",
            "creationDate": "2020-07-02T12:50:00.000Z",
            "tags": [
                "landscape",
                "sunset",
                "mountains"
            ]
        },
        {
            "id": "5fc1cfc54a34727262b2a33b",
            "previewBmp": "/images/previews/5fc1cfc54a34727262b2a33b_preview.bmp",
            "uploader": "test2",
            "creator": "Test Creator",
            "creationDate": "2020-07-02T12:50:00.000Z",
            "tags": [
                "landscape",
                "sunset",
                "mountains"
            ]
        },
        {
            "id": "5fc235a2639b4f25ea0d32fb",
            "previewBmp": "/images/previews/5fc235a2639b4f25ea0d32fb_preview.bmp",
            "uploader": "test",
            "creator": "Test Creator",
            "creationDate": "2020-07-02T12:50:00.000Z",
            "tags": [
                "landscape",
                "sunset",
                "mountains"
            ]
        }
    ]
}

My caffs

Purpose: gets all the caff files the user uploaded.

Endpoint: GET /api/my-caffs

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database

Response

Successful response: 200 OK Successful response body:

{ 
    'caffs': [
        {
            'id': '...', //<- ObjectId
            'previewBmp': '...',  //<- string path to server static image
            'uploader': '...', //<- string username
            'creator': '...', //<- string
            'creationDate': ..., //<- Date 
            'tags': [
               'tag1', //<- string
               'tag2',
               // ...
            ]
        },
        //...
    ]
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/my-caffs' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTYyMDQwLCJleHAiOjE2MDY1NjQ0NDB9.r3zj85Co02nS3PbDzcB-GSkMUoEWyoSJkcB8YW0m5EM' \
--insecure

Example valid response

{
    "caffs": [
        {
            "id": "5fc235a2639b4f25ea0d32fb",
            "previewBmp": "/images/previews/5fc235a2639b4f25ea0d32fb_preview.bmp",
            "uploader": "test",
            "creator": "Test Creator",
            "creationDate": "2020-07-02T12:50:00.000Z",
            "tags": [
                "landscape",
                "sunset",
                "mountains"
            ]
        }
    ]
}

Comment

Purpose: send comment to caff.

Endpoint: POST /api/caff/%caffid%/comment

Payload

{ 'comment': '...' //<- comment string }

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist

Response

Successful response: 200 OK Successful response body:

{ 
    'commentId': '...' //<- ObjectId
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request POST 'https://localhost:3000/api/caff/5fc235a2639b4f25ea0d32fb/comment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--data-raw '{"comment": "teszt komment"}' \
--insecure

Example valid response

{
    "commentId": "5fc23b38639b4f25ea0d32fc"
}

Get caff details

Purpose: get the details of one caff.

Endpoint: GET /api/caff/%caffid%

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist

Response

Successful response: 200 OK Successful response body:

{ 'caff': {
    'id': '...', //<- ObjectId
    'previewBmp': '...',  //<- string path to server static image
    'uploader': '...', //<- string username
    'creator': '...', //<- string
    'creationDate': '...', //<- Date
    'isOwner': '...', //<- boolean (if requesting user uploaded it or already bought it it's true, else false)
    'tags': [
       'tag1', //<- string
       'tag2',
       // ...
    ],
    'comments': [
       {
         'id': '...', //<- ObjectId
         'comment': '...', //<- string comment text
         'user': '...', //<- string username
         'date': '...' //<- Date
       },
       //...
    ]
  }
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/caff/5fc235a2639b4f25ea0d32fb' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--insecure

Example valid response

{
    "caff": {
        "id": "5fc235a2639b4f25ea0d32fb",
        "previewBmp": "/images/previews/5fc235a2639b4f25ea0d32fb_preview.bmp",
        "uploader": "test",
        "creator": "Test Creator",
        "creationDate": "2020-07-02T12:50:00.000Z",
        "isOwner": false,
        "tags": [
            "landscape",
            "sunset",
            "mountains"
        ],
        "comments": [
            {
                "id": "5fc23b38639b4f25ea0d32fc",
                "comment": "teszt komment",
                "user": "test",
                "date": "2020-11-28T11:57:44.137Z"
            }
        ]
    }
}

Buy caff

Purpose: buy a caff.

Endpoint: GET /api/caff/%caffid%/buy

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist

Note: if caff is already bought by the user, then it will successfully return the previous transaction's id.

Response

Successful response: 200 OK Successful response body:

{ 
   'transactionId': '...' //<- ObjectId
}

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/caff/5fc235a2639b4f25ea0d32fb/buy' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--insecure

Example valid response

{
    "transactionId": "5fc23d80639b4f25ea0d32fe"
}

Download caff

Purpose: download a previously bought a caff.

Endpoint: GET /api/caff/%caffid%/download

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist
the caff with %caffid% should be already bought (with using appropriate endpoint) by the user

Response

Successful response: 200 OK Successful response body: the caff file as raw octet stream

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/caff/5fc235a2639b4f25ea0d32fb/download' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--output test.caff \
--insecure

Example valid response

The caff file should be downloaded as test.caff.

Delete comment

Purpose: download a previously bought a caff.

Endpoint: GET /api/caff/%caffid%/%commentid%/delete

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist
the comment with %commentid% should exist and be a comment of caff with %caffid%
the comment with %commentid% should be owned by the user with username (or user should be admin)

Response

Successful response: 200 OK Successful response body:

None.

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/caff/5fc235a2639b4f25ea0d32fb/5fc23b38639b4f25ea0d32fc/delete' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--insecure

Example valid response

None.

Delete caff

Purpose: download a previously bought a caff.

Endpoint: GET /api/caff/%caffid%/delete

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database
the caff with %caffid% should exist
the caff with %caffid% should be owned by the user (or user should be admin)

Response

Successful response: 200 OK Successful response body:

None.

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/caff/5fc3af1595e7c06f43bb54a3/delete' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2Njc5Mjc0LCJleHAiOjE2MDY2ODE2NzR9.CNN7cUTMimAPe6Ll9fVeVacEDEa5KfVh1I739nX4jsA' \
--insecure

Example valid response

None.

Get user data

Purpose: get user's email and other data.

Endpoint: GET /api/user

Payload

None.

Request requirements:

JWT should be valid
JWT should contain username that exists in the database

Response

Successful response: 200 OK Successful response body:

{ 'user': { 'username': '...', //<- string 'email': '...', //<- string 'isAdmin': '...', //<- boolean 'id': '...' //<- ObjectId } }

Unsuccessful response: 400 BAD

Example valid curl call

curl --location --request GET 'https://localhost:3000/api/user' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJpc0FkbWluIjpmYWxzZSwiaWF0IjoxNjA2NTY0NjQ5LCJleHAiOjE2MDY1NjcwNDl9.5KDnWJkptpndoNxIl3P1Hw8cdGr1yRzpr5qPc7k7tI4' \
--insecure

Example valid response

{
    "user": {
        "username": "test",
        "email": "test@test",
        "isAdmin": false,
        "id": "5fc22fcf75d4992285c03e29"
    }
}