Squad Game API Documentation - bounswe/2021SpringGroup6 GitHub Wiki

API Documentation

User Related Endpoints

/users POST - Create a User

Endpoint: /users
Method: POST
Authorization: Not Needed
Author: Berk Atıl
Body Parameters:

 {
             “email” :Email of the user, required
             “password” : Password of the user. It should be at least 8 characters and at most 15 characters. Alphanumeric characters, _, *, and . are allowed. required
             “identifier” : Identifier(username) of the user. required
             “name” : First name of the user.
             “familyName” : Last name of the user.
             “birthDate” : Birth date of the user. It should be YYYY-MM-DD format.
             “gender” : Gender of the user. It can be male, female or decline_to_report.
             “sports” : Skill levels of the user for different sports. It is a list of dictionaries and each dictionary contain sport name and skill level
             “latitude” : latitude of the user. not required.     
             “longitude” : latitude of the user. not required.      
}

Responses:
201: ""
400: "Body parameters are not correct."
Example Response:

{
              "message": "There is an error regarding the provided data"
}

400: "Given sport is not supported."
Example Response:

{
              "message": "Given sport is not supported."
}

400: "Username is already taken"
Example Response:

{
              "message": "Username is already taken"
}

400: "Email is already taken"
Example Response:

{
              "message": "Email is already taken"
}

400: "There is an integrity error."
Example Response:

{
              "message": "There is an integrity error."
}

500:"There is an internal error, try again later."

{
              "error": "There is an internal error, try again later."
}

/users/login POST - Login

Endpoint: /users/login/
Method: POST
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Body Parameters:

 {
             “identifier” : Identifier(username) of the user. required
             “password” : Password of the user. required
}

Expected Response When No Error:

{
             "token": Authorization token for the user.
             "user_id": Id of the user.
}

Responses:
200: "User is authenticated." Example Response:

{
              "token": "952c07e2afc8fd0307fd3eb5c130526d3d43ac3c",
              "user_id": 5,
}

400: "Body parameters are not correct."
Example Response:

{
    "message": {
        "identifier": [
            "Ensure this field has at least 3 characters."
        ]
    }
}

403: "Credentials are not correct."
Example Response:

{
    "message": "Check credentials."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/logout POST - Logout

Endpoint: /users/logout/
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Header Parameters:

Authorization: Token <Token of the user>

Expected Response When No Error:

{
    "message": "Successfully logged out."
}

Responses:
200: "User successfully logged out." Example Response:

{
    "message": "Successfully logged out."
}

401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/following POST - Follow User

Endpoint: /users/<user_id>/following/
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the following user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

{
             “user_id”: Id of the user to follow. required
}

Responses:
200: "User successfully followed."
401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

403: "Not allowed to follow for another user."

{
    "message": "Not allowed to follow for another user."
}

400: "Input not correct."

{
    "user_id": [
        "A valid integer is required."
    ]
}

{
    "message": "User cannot follow itself."
}

{
    "message": "Enter a valid user_id to follow."
}

{
    "message": "User already followed."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/following DELETE - Unfollow User

Endpoint: /users/<user_id>/following/
Method: DELETE Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the following user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

{
             “user_id”: Id of the user to unfollow. required
}

Responses:
200: "User successfully unfollowed."
401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

403: "Not allowed to unfollow for another user."

{
    "message": "Not allowed to unfollow for another user."
}

400: "Input not correct."

{
    "user_id": [
        "A valid integer is required."
    ]
}

{
    "message": "Enter a valid user_id to follow."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/following GET - Get Users Followed By User

Endpoint: /users/<user_id>/following Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the following user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
200: Example Response:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "summary": "lion3's following activities.",
    "type": "Collection",
    "total_items": 1,
    "items": [
        {
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "lion3 followed esb",
            "type": "Follow",
            "actor": {
                "type": "https://schema.org/Person",
                "@id": 16,
                "identifier": "lion3"
            },
            "object": {
                "type": "https://schema.org/Person",
                "@id": 3,
                "identifier": "esb"
            }
        }
    ]
}

401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

400: "Input not correct."

{
    "message": "User does not exist."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/follower GET - Get Users Follow User

Endpoint: /users/<user_id>/follower Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the following user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
200: Example Response:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "summary": "esb's being followed activities.",
    "type": "Collection",
    "total_items": 3,
    "items": [
        {
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "lion followed esb",
            "type": "Follow",
            "actor": {
                "type": "https://schema.org/Person",
                "@id": 8,
                "identifier": "lion"
            },
            "object": {
                "type": "https://schema.org/Person",
                "@id": 3,
                "identifier": "esb"
            }
        },
        {
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "esb18 followed esb",
            "type": "Follow",
            "actor": {
                "type": "https://schema.org/Person",
                "@id": 10,
                "identifier": "esb18"
            },
            "object": {
                "type": "https://schema.org/Person",
                "@id": 3,
                "identifier": "esb"
            }
        },
        {
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "lion3 followed esb",
            "type": "Follow",
            "actor": {
                "type": "https://schema.org/Person",
                "@id": 16,
                "identifier": "lion3"
            },
            "object": {
                "type": "https://schema.org/Person",
                "@id": 3,
                "identifier": "esb"
            }
        }
    ]
}

401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

400: "Input not correct."

{
    "message": "User does not exist."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/blocked POST - Block User

Endpoint: /users/<user_id>/blocked/
Method: POST
Authorization: Needed
Author: Berk Atıl
Path Parameters:

user_id: user_id of the blocking user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

{
             “user_id”: Id of the user to block. required
}

Responses:
200:
401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

403: "Not allowed to block for another user."

{
    "message": "Not allowed to block for another user."
}

400: "Input not correct."

{
    "user_id": [
        "A valid integer is required."
    ]
}

{
    "message": "User cannot block itself."
}

{
    "message": "Enter a valid user_id to block."
}

{
    "message": "User already blocked."
}

500:"There is an error, try later."

{
    "message": "An error occured, please try again later."
}

/users/<user_id>/blocked DELETE - Unblock User

Endpoint: /users/<user_id>/blocked/
Method: DELETE
Authorization: Needed
Author: Berk Atıl
Path Parameters:

user_id: user_id of the blocking user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

{
             “user_id”: Id of the user to unblock. required
}

Responses:
200:
401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

403: "Not allowed to unblock for another user."

{
    "message": "Not allowed to unblock for another user."
}

400: "Input not correct."

{
    "user_id": [
        "A valid integer is required."
    ]
} 

{
    "message": "User cannot block itself."    
}  

{
    "message": "Enter a valid user_id to unblock."   
}

500: "There is an error, try later."

{
    "message": "An error occured, please try again later."
}

/users/<user_id>/blocked GET - Get Users Blocked By User

Endpoint: /users/<user_id>/blocked
Method: GET
Authorization: Needed
Author: Berk Atıl
Path Parameters:

user_id: user_id of the blocking user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
200: Example Response:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "summary": "lion3's blocking activities.",
    "type": "Collection",
    "total_items": 1,
    "items": [
        {
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "lion3 blocked esb",
            "type": "Block",
            "actor": {
                "type": "https://schema.org/Person",
                "@id": 16,
                "identifier": "lion3"
            },
            "object": {
                "type": "https://schema.org/Person",
                "@id": 3,
                "identifier": "esb"
            }
        }
    ]
}

401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "Login required."
}

400: "Input not correct."

{
    "message": "User does not exist."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id> GET - Get User

Endpoint: /users/<user_id>
Method: GET
Authorization: Not Needed to see other users but needed to see own data.
Author: Berk Atıl

Path Parameters:

user_id: user_id of the desired user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Expected Response When No Error:

{
             "email": Email of the user.
             "user_id": Id of the user.
             "name": First name of the user
             "familyName": Last name of the user.
             "birthDate": Birth date of the user.
             "gender": Gender of the user.
             "@context": Context of the user based on scheme.
             "@id": Id of the user.
             "knowsAbout": Skill levels of the user for different sports.
             "@type":
}

Responses:
200: "User is returned." Example Response:

{
             "email": "[email protected]",
             "user_id": 1,
             "name": "Berk",
             "familyName": "",
             "birthDate": null,
             "gender": "male",
             "@context": "https://schema.org/Person",
             "@id": 1,
             "knowsAbout": [
                           {
                            "@type": "PropertyValue",
                            "name": "soccer",
                            "value": 2
                           }]
             "@type": "Person"
}

401: "User does not exist"
Example Response:

{
    "message": "User id does not exist"
}

500: "An error occurred, please try again later"

{
    "message": "An error occurred, please try again later"
}

/users/<user_id> DELETE - Delete User

Endpoint: /users/<user_id>
Method: DELETE
Authorization: Needed
Author: Berk Atıl
Path Parameters:

user_id: user_id of the user that will be deleted, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
200: "User successfully deleted."
401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "User not logged in."
}

400: "User cannot delete others' accounts."

{
    "message": "User cannot delete others' accounts."
}

500:"There is an error, try later."

{
    "message": "An error occured, please try again later."
}

/users/<user_id> PUT - Update User Information

Endpoint: /users/<user_id>
Method: PUT
Authorization: Needed
Author: Berk Atıl

Path Parameters:

user_id: user_id of the desired user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

 {
             “email” :Email of the user
             “name” : First name of the user.
             “familyName” : Last name of the user.
             “birthDate” : Birth date of the user. It should be YYYY-MM-DD format.
             “gender” : Gender of the user. It can be male, female or decline_to_report.
             “sports” : Skill levels of the user for different sports. It is a list of dictionaries and each dictionary contain sport name and skill level
             “latitude” : latitude of the user.    
             “longitude” : latitude of the user.    
}

Responses:
200: "User information is updated." 400: "Input not correct."

{
    "gender": [
        "The gender could be male, female or decline_to_report."
    ]
}

401: "Login required"
Example Response:

{
    "message": "Login required."
}

500: "An error occurred, please try again later"

{
    "message": "An error occurred, please try again later"
}

/users/recover POST - Recover Password

Endpoint: /users/recover
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Body Parameters:

{
             “email”: email of the user who forgot their password. required
}

Responses:
200: "User successfully unfollowed." Example Response:

{
    "message": "If email provided is correct, a reset password is sent, please check spam."
}

401: "Already logged in."
Example Response:

{
    "message": "Already logged in use change password on settings instead."
}

400: "Input not correct."

{
    "message": {
        "email": [
            "Enter a valid email address."
        ]
    }
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/users/<user_id>/visible_attributes PUT - Change Visible Attributes

Endpoint: /users/<user_id>/visible_Attributes
Method: PUT
Authorization: Needed
Author: Berk Atıl

Path Parameters:

user_id: user_id of the desired user, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

 {
             “email_visibility” : Boolean value that represents if email information can be shown to others.  
             “name_visibility” : Boolean value that represents if first name information can be shown to others.  
             “familyName_visibility” : Boolean value that represents if family name information can be shown to others.  
             “birthDate_visibility” : Boolean value that represents if birth date information can be shown to others.  
             “gender_visibility” : Boolean value that represents if gender information can be shown to others.  
             “location_visibility” : Boolean value that represents if location information can be shown to others.  
}

Responses:
200:
400: "Input not correct."

{
    "gender_visibility": [
        "The gender_visibility could be True or False."
    ]
}

401: "Login required"
Example Response:

{
    "message": "Login required."
}

403: "Users cannot change other users' visibility information"

{
    "message": "Users cannot change other users' visibility information"
}

500: "An error occurred, please try again later."

{
    "message": "An error occurred, please try again later."
}

/users/<user_id>/participating GET - Get Users Participating Events

Endpoint: /users/<user_id>/participating Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the desired user, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/Person",
    "@id": id of the person,
    "additionalProperty" : {
                    "@type": "PropertyValue",
                    "name": "participatingEvents",
                    "value": list of participating events
                }
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/Person",
    "@id": 4,
    "identifier": "lion3",
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "participatingEvents",
        "value": [
            {
                "type": "https://schema.org/SportsEvent",
                "@id": 5,
                "name": "Soccer Event",
                "sport": "soccer",
                "startDate": "2021-12-10T19:00:00Z",
                "location": {
                    "@context": "https://schema.org",
                    "@type": "Place",
                    "geo": {
                        "@type": "GeoCoordinates",
                        "latitude": 41.002697,
                        "longitude": 39.716763
                    },
                    "address": "Ortahisar, Trabzon, Turkey"
                },
                "maximumAttendeeCapacity": 12
            }
        ]
    }
}

400: Example Response:

{
              "message": "User does not exist."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/users/<user_id>/spectating GET - Get Users Spectating Events

Endpoint: /users/<user_id>/spectating Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the desired user, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/Person",
    "@id": id of the person,
    "additionalProperty" : {
                    "@type": "PropertyValue",
                    "name": "spectatingEvents",
                    "value": list of spectating events
                }
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/Person",
    "@id": 5,
    "identifier": "Ekrem321",
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "spectatingEvents",
        "value": [
            {
                "type": "https://schema.org/SportsEvent",
                "@id": 3,
                "name": "lets s play soccer",
                "sport": "soccer",
                "startDate": "2021-12-18T13:00:00Z",
                "location": {
                    "@context": "https://schema.org",
                    "@type": "Place",
                    "geo": {
                        "@type": "GeoCoordinates",
                        "latitude": 41.002697,
                        "longitude": 39.716763
                    },
                    "address": "Ortahisar, Trabzon, Turkey"
                },
                "maxSpectatorCapacity": 59
            },
            {
                "type": "https://schema.org/SportsEvent",
                "@id": 5,
                "name": "Soccer Event",
                "sport": "soccer",
                "startDate": "2021-12-10T19:00:00Z",
                "location": {
                    "@context": "https://schema.org",
                    "@type": "Place",
                    "geo": {
                        "@type": "GeoCoordinates",
                        "latitude": 41.002697,
                        "longitude": 39.716763
                    },
                    "address": "Ortahisar, Trabzon, Turkey"
                },
                "maxSpectatorCapacity": 24
            }
        ]
    }
}

400: Example Response:

{
              "message": "User does not exist."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/users/<user_id>/interested GET - Get Users Interested Events

Endpoint: /users/<user_id>/interested Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the desired user, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/Person",
    "@id": id of the person,
    "additionalProperty" : {
                    "@type": "PropertyValue",
                    "name": "interestedEvents",
                    "value": list of interested events
                }
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/Person",
    "@id": 5,
    "identifier": "Ekrem321",
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "interestedEvents",
        "value": [
            {
                "type": "https://schema.org/SportsEvent",
                "@id": 3,
                "name": "lets s play soccer",
                "sport": "soccer",
                "startDate": "2021-12-18T13:00:00Z",
                "location": {
                    "@context": "https://schema.org",
                    "@type": "Place",
                    "geo": {
                        "@type": "GeoCoordinates",
                        "latitude": 41.002697,
                        "longitude": 39.716763
                    },
                    "address": "Ortahisar, Trabzon, Turkey"
                },
                "maxSpectatorCapacity": 59
            },
            {
                "type": "https://schema.org/SportsEvent",
                "@id": 5,
                "name": "Soccer Event",
                "sport": "soccer",
                "startDate": "2021-12-10T19:00:00Z",
                "location": {
                    "@context": "https://schema.org",
                    "@type": "Place",
                    "geo": {
                        "@type": "GeoCoordinates",
                        "latitude": 41.002697,
                        "longitude": 39.716763
                    },
                    "address": "Ortahisar, Trabzon, Turkey"
                },
                "maxSpectatorCapacity": 24
            }
        ]
    }
}

400: Example Response:

{
              "message": "User does not exist."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/users/<user_id>/badges POST - Give User A Badge

Endpoint: /users/<user_id>/badges
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the user to give the badge to, integer.

Body Parameters:

{
    "badge": name of the badge, required
}

Responses:
201: "Badge Given"
400: Example Response:

{
              "message": "Users cannot give badge to themselves."
}

{
              "message": "Enter a valid badge."
}

{
              "message": "Already gave this badge to this user."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/users/<user_id>/badges GET - Get User Badges

Endpoint: /users/<user_id>/badges Method: GET Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

user_id: user_id of the user to give the badge to, integer.

Notes:
Event badges are returned when the startDate of the event passes. Expected Response When No Error:

{
    "@context": "https://schema.org/Person".
    "@id": Id of the user.
    "additionalProperty": [
        {
            "@type": "PropertyValue",
            "name": "event_badges",
            "value": [list of event badges]
        },
        {
            "@type": "PropertyValue",
            "name": "user_badges",
            "value": [list of user badges]
        }]
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/Person",
    "@id": 4,
    "additionalProperty": [
        {
            "@type": "PropertyValue",
            "name": "event_badges",
            "value": [
                {
                    "@context": "https://www.wikidata.org/entity/Q107264587",
                    "name": "encouraging",
                    "additionalProperty": {
                        "@type": "PropertyValue",
                        "name": "event",
                        "value": {
                            "@context": "https://schema.org/SportsEvent",
                            "@id": 5
                        }
                    }
                }
            ]
        },
        {
            "@type": "PropertyValue",
            "name": "user_badges",
            "value": [
                {
                    "@context": "https://www.wikidata.org/entity/Q16519308",
                    "name": "friendliness",
                    "additionalProperty": {
                        "@type": "PropertyValue",
                        "name": "givenBy",
                        "value": {
                            "@context": "https://schema.org/Person",
                            "@id": 1
                        }
                    }
                }
            ]
        }
    ]
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/users/searches POST - Search Users

Endpoint: /users/searches
Method: POST
Authorization: Not Needed.
Author: Berk Atıl

Body Parameters:

 {
             “name” : Name of the user, it can be sub-name.  
             “familyName” : Family Name of the user, it can be sub-name
             “identifier” : Username/identifier of the user, it can be sub-word as well.
}

Expected Response When No Error:

{
    "@context": "https://www.w3.org/ns/activitystreams",     
    "type": "Collection",
    "total_items": 1,
    "items": [
              {
             "email": "[email protected]",
             "user_id": 1,
             "name": "Berk",
             "familyName": "",
             "birthDate": null,
             "gender": "male",
             "@context": "https://schema.org/Person",
             "@id": 1,
             "knowsAbout": [
                           {
                            "@type": "PropertyValue",
                            "name": "soccer",
                            "value": 2
                           }]
             "@type": "Person"
              }
]
}

Responses:
200: "Users are returned." Example Response:

{
"@context": "https://www.w3.org/ns/activitystreams",     
    "type": "Collection",
    "total_items": 1,
    "items": [
              {
             "email": "[email protected]",
             "user_id": 1,
             "name": "Berk",
             "familyName": "",
             "birthDate": null,
             "gender": "male",
             "@context": "https://schema.org/Person",
             "@id": 1,
             "knowsAbout": [
                           {
                            "@type": "PropertyValue",
                            "name": "soccer",
                            "value": 2
                           }]
             "@type": "Person"
              }
]
}

400: "Body parameters are not correct."
Example Response:

{
    "message": {
        "name": [
            "Exactly 1 filter should be provided. Options are name, familyName and identifier""
        ]
    }
}

500:"There is an internal error, try again later."

{
              "message": "Try later."
}

Sport Related Endpoints

/sports GET - Get Sports

Endpoint: /sports
Method: GET
Authorization: Not Needed.
Author: Berk Atıl

Expected Response When No Error:

{
            "sport_names": ['soccer','basketball',...]
}

Responses:
200: "Sports are returned" Example Response:

{
            "sport_names": ['soccer','basketball',...]
}

500:"There is an internal error, try again later."

{
    "message": "There is an internal error, try again later."
}

Event Related Endpoints

/events POST - Create Event

Endpoint: /events
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Body Parameters:

 {
             “name” :Name of the event, required
             “sport” : Sport of the event. Must be a sport stored in the system. required
             “description” : Description for the event.
             “startDate” : Date and time of the event. Must be in [iso-8601](https://www.w3.org/TR/NOTE-datetime) format, should include time. required 
             “latitude” : Latitude of the location of the event. required
             “longitude” : Longitude of the location of the event. required
             “minimumAttendeeCapacity” : Minimum number of attendees required for the event. required
             “maximumAttendeeCapacity” : Maximum number of attendees for the event. required
             “maxSpectatorCapacity” : Maximum number of spectators for the event. required
             “minSkillLevel” : Minimum skill level of the users for the event. required
             “maxSkillLevel” : Maximum skill level of the users for the event. required
             “acceptWithoutApproval” : Boolean indicating whether approval from the organizer is required for participating. required
             “duration” : Duration of the event in minutes. required
             "canEveryoneSeePosts": If everyone can see posts. default true. not required
             "canEveryonePostPosts": If everyone can post posts. default true. not required
}

Expected Response When No Error:

{
             "@context": "https://schema.org/SportsEvent".
             "@id": Id of the new event.
}

Responses:
201: "Event Created"
Example Response:

{         
              "@context": "https://schema.org/SportsEvent",
              "@id": 1
}

400: "Body parameters are not correct."
Example Response:

{
    "message": {
        "latitude": [
            "Ensure this value is less than or equal to 90."
        ]
    }
}

400: "Coordinated does not correspond to a valid place."
Example Response:

{
              "message": "Check coordinates."
}

401: "Login required"
Example Response:

{
    "message": "User not logged in."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id> GET - Get Event

Endpoint: /events/<event_id>
Method: GET
Authorization: Not Needed.
Author: Berk Atıl

Path Parameters:

user_id: event_id of the desired event, integer.

Expected Response When No Error:

{
             "@context": Context of the event based on scheme.
             "@type": Type of the event.
             "name": Name of the event.  
             "location": Information about the location of the event.  
             "organizer": Information about the organizer of the event.  
             "attendee": Information about the participants of the event.  
             "audience": Context of the user based on scheme.
             "additionalProperty": Additional information about the event.   
             "knowsAbout": Skill levels of the user for different sports.
             "event_id": Id of the event.  
             "name": Name of the event.   
             "sport": Sport type of the event.    
             "description": Description of the event.    
             "startDate": Date of the event.    
             "maximumAttendeeCapacity": Maximum participants that can attend to the event.    
             "minSkillLevel": Minimum skill level required for the event.    
             "maxSkillLevel": Maximum skill level required for the event.    
             "duration": Duration of the event.  
             "created_on": Creation date of the event.  
}

Responses:
200: "Event is returned." Example Response:

{
             "@context": "https://schema.org",
             "@type": "SportsEvent",
             "name": "let's play soccer.",  
             "event_id": 1,
             "sport": "soccer"    
             "description": "Have a nice match",   
             "startDate": "2021-12-21T19:00:00Z", 
             "maximumAttendeeCapacity": 5,  
             "minSkillLevel": 1,
             "maxSkillLevel": 3,   
             "duration": 90
             "created_on": "2021-12-12T11:24:02.367571Z",  
             "location": {
                           "@context": "https://schema.org",
                           "@type": "Place",
                           "geo": {
                                   "@type':"GeoCoordinates",
                                   "latitude": 32.456,
                                   "longitude": 45.321
            },
            "address": "Sariyer, Istanbul, Turkey"
        }
             "organizer": {
                            "@context":"https://schema.org",    
                            "@type":"Person",   
                            "@id':2,   
                            "identifier":"lion"
                           }
             "attendee":[
                         {
                          "@context":"https://schema.org",    
                          "@type":"Person",    
                          "@id": 2, 
                          "identifier": "cat"
                         }
                        ]
             "audience": [
                         {
                          "@context":"https://schema.org",    
                          "@type":"Person",    
                          "@id": 4, 
                          "identifier": "lion3"
                         }
                        ]
             "additionalProperty": [
                                    {
                                     "@type": "PropertyValue",
                                     "name": "minimumAttendeeCapacity",
                                     "value": 3
                                    },  
                                    {
                                     "@type": "PropertyValue",
                                     "name": "maxSpectatorCapacity",
                                     "value": 10
                                    },
                                    {
                                     "@type": "PropertyValue",
                                     "name": "interesteds",
                                     "value":[
                                              {
                                               "@context":"https://schema.org",   
                                               "@type":"Person",   
                                               "@id": 8, 
                                               "identifier":"lion8"
                                              }
                                             ]
                                    },
                                    {
                                     "@type": "PropertyValue",
                                     "name": "acceptWithoutApproval",
                                     "value": False
                                    }
                                  ]   
}

401: "Event id does not exist"
Example Response:

{
    "message": "Event id does not exist"
}

500: "An error occurred, please try again later"

{
    "message": "An error occurred, please try again later"
}

/events/<event_id> PUT - Update Event

Endpoint: /events/<event_id>
Method: PUT
Authorization: Needed
Author: Berk Atıl

Path Parameters:

event_id: event_id of the desired event, integer.

Header Parameters:

Authorization: Token <Token of the user>

Body Parameters:

 {
             “name” :Name of the event
             “description” : Description of the event.
             “startDate” : Date and time of the event. Must be in [iso-8601](https://www.w3.org/TR/NOTE-datetime) format, should include time. 
             “latitude” : Latitude of the event place.
             “longitude” : Longitude of the event place.
             “minimumAttendeeCapacity“: Minimum number of attendees required for the event.
             “maximumAttendeeCapacity” : Maximum number of attendees for the event.
             “maxSpectatorCapacity” : Maximum number of spectators for the event.
             “minSkillLevel” : Minimum skill level of the users for the event. 
             “maxSkillLevel” : Maximum skill level of the users for the event.
             “duration” : DUration of the event
}

Responses:
200: "Event information is updated."
400: "Input not correct."

{
    "minimumAttendeeCapacity": [
        "The minimumAttendeeCapacity must be greater than 0."
    ]
}

400: "Input not correct."

{
   "message": "There are more participants than requested maximumAttendeeCapacity."
}

400: "Input not correct."

{
   "message": "There is a participant with lower skill level than requested minSkillLevel."
}

400: "Input not correct."

{
   "message": "There is a participant with higher skill level than requested maxSkillLevel."
}

400: "Input not correct."

{
   "message": "There are more spectators than requested maxSpectatorCapacity."
}

401: "Login required"
Example Response:

{
    "message": "Login required."
}

500: "An error occurred, please try again later"

{
    "message": "An error occurred, please try again later"
}

/events/<event_id> DELETE - Delete Event

Endpoint: /events/<event_id>
Method: DELETE
Authorization: Needed
Author: Berk Atıl
Path Parameters:

event_id: event_id of the event that will be deleted, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
204: "Event successfully deleted."
400: "Wrong Input"
Example Response:

{
    "message": "Try with a valid event."
}

401: "Invalid token."
Example Response:

{
    "message": "Invalid token."
}

{
    "message": "User not logged in."
}

403: "Only organizers can delete events."

{
    "message": "Only organizers can delete events."
}

500:"There is an error, try later."

{
    "message": "Try later."
}

/events/searches POST - Search or Filter Events

Endpoint: /events/searches
Method: POST
Authorization: Not Needed.
Author: Berk Atıl

Body Parameters:

 {
             “creator” : Creator of an event.  
             “nameContains” : String that can be in the name of an event.  
             “timeBetweenStart” : The Earliest Time in iso-8601 format. (HH:MM:SS.sss)  
             “timeBetweenEnd” : The Latest Time in iso-8601 format. (HH:MM:SS.sss ) 
             “dateBetweenStart” : The Earliest Date in iso-8601 format. (YYYY-MM-DD)  
             “dateBetweenEnd” : The Latest Date in iso-8601 format. (YYYYY-MM-DD)  
             “latitudeBetweenStart” : Minimum Latitude Value.    
             “latitudeBetweenEnd” :  Maximum Latitude Value.    
             “longitudeBetweenStart” : Minimum Longitude Value.  
             “longitudeBetweenEnd” : Maximum Longitude Value.   
             “city” : City information.  
             “district” : District information.   
             “country” : Country information.   
             “sport” : Sport type information.  
             “skillLevel” : List of skill levels.
             “sortBy” : Attribute that will be used to sort events.(It can be distance, startDate, or skillLevel)
             “order” : Either ascending or descending
}

Expected Response When No Error:

{
              "@context":Context of the returned events.,   
              "type":Type of the returned object,  
              "total_items":Total number of events that are returned, 
              "items": List of events
}

Responses:
200: "Events are returned." Example Response:

{
 "@context":"https://www.w3.org/ns/activitystreams",   
 "type":"OrderedCollection",  
 "total_items":", 
 "items":
 [
  {
             "@context": "https://schema.org"
             "@type": "SportsEvent"
             "name": "let's play soccer."  
             "location": {
                           "@context": "https://schema.org",
                           "@type": "Place",
                           "geo": {
                                   "@type':"GeoCoordinates",
                                   "latitude": 32.456,
                                   "longitude": 45.321
            },
            "address": "Sariyer, Istanbul, Turkey"
        }
             "organizer": {
                            "@context":"https://schema.org",    
                            "@type":"Person",   
                            "@id':2,   
                            "identifier":"lion"
                           }
             "attendee":[
                         {
                          "@context":"https://schema.org",    
                          "@type":"Person",    
                          "@id": 2, 
                          "identifier": "cat"
                         }
                        ]
             "audience": [
                         {
                          "@context":"https://schema.org",    
                          "@type":"Person",    
                          "@id": 4, 
                          "identifier": "lion3"
                         }
                        ]
             "additionalProperty": [
                                    {
                                     "@type": "PropertyValue",
                                     "name": "minimumAttendeeCapacity",
                                     "value": 3
                                    },  
                                    {
                                     "@type": "PropertyValue",
                                     "name": "maxSpectatorCapacity",
                                     "value": 10
                                    },
                                    {
                                     "@type": "PropertyValue",
                                     "name": "interesteds",
                                     "value":[
                                              {
                                               "@context":"https://schema.org",   
                                               "@type":"Person",   
                                               "@id": 8, 
                                               "identifier":"lion8"
                                              }
                                             ]
                                    },
                                    {
                                     "@type": "PropertyValue",
                                     "name": "acceptWithoutApproval",
                                     "value": False
                                    }
                                  ]   
             "event_id": Id of the event.  
             "name": Name of the event.   
             "sport": Sport type of the event.    
             "description": Description of the event.    
             "startDate": Date of the event.    
             "maximumAttendeeCapacity": Maximum participants that can attend to the event.    
             "minSkillLevel": Minimum skill level required for the event.    
             "maxSkillLevel": Maximum skill level required for the event.    
             "duration": Duration of the event.  
             "created_on": Creation date of the event.  
  }
 ]
}

400: "Input not correct."

{
    "latitude": "latitudeBetweenStart and latitudeBetweenEnd must be given together."
}

{
   "longitude": "longitudeBetweenStart and longitudeBetweenEnd must be given together."
}

{
   "time": "timeBetweenStart should be smaller than or equal to timeBetweenEnd"
}

{
  "city": "city and coordinate information must not be given together"
}

{
  "district": "district and coordinate information must not be given together"
}

{
  "country": "country and coordinate information must not be given together"
}

/events/<event_id>/participants GET - Get Event Participants

Endpoint: /events/<event_id>/participants
Method: GET
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": id of the event,
    "attendee": list of person schemas of the participants
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": 1,
    "attendee": [
        {
            "@context": "https://schema.org/Person",
            "@id": 3,
            "identifier": "lion"
        }
    ]
}

400: Example Response:

{
              "message": "Try with a valid event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/participants POST - Accept And Reject Participants

Endpoint: /events/<event_id>/participants
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Notes: Users are evaluated starting from accept_user_list on given order. Therefore if a user is both on accept and reject list, it will be accepted. If capacity gets full while evaluating, first users will get the place therefore the order is important. Path Parameters:

event_id: event_id of the desired event, integer.

Body Parameters:

{
    "accept_user_id_list": list of user ids to accept the event,
    "reject_user_id_list": list of user ids to accept the event,
}

Expected Response When No Error:

{
     "@context": "https://www.w3.org/ns/activitystreams",
     "summary": "user_name_of_the_organize accepted and rejected users to event_name event",
     "type": "Collection",
     "items": list of accepting and rejection activities,
     "total_items": number of activities
}

Responses:
201:
Example Response:

{
     "@context": "https://www.w3.org/ns/activitystreams",
     "summary": "user accepted and rejected users to 'lets play' event",
     "type": "Collection",
     "items":  [
                   {
                      "@context": "https://www.w3.org/ns/activitystreams",
                      "summary": "user accepted user2 to event 'lets play'.",
                      "type": "Accept",
                      "actor": {
                               "type": "https://schema.org/Person",
                               "@id": 1,
                               "identifier": user
                               },
                      "object": {
                               "type": "RequestToParticipate",
                               "actor": {
                                        "type": "https://schema.org/Person",
                                        "@id": 2,
                                        "identifier": user2
                                        },
                               "object": {
                                        "type": "https://schema.org/SportsEvent",
                                        "@id": 1
                                         }
                                   }
                       },
                       {
                         "@context": "https://www.w3.org/ns/activitystreams",
                         "summary": "user rejected user3's request to join the event 'lets play'.",
                         "type": "Reject",
                         "actor": {
                                  "type": "https://schema.org/Person",
                                  "@id": 1,
                                  "identifier": user
                                  },
                          "object": {
                                  "type": "RequestToParticipate",
                                  "actor": {
                                           "type": "https://schema.org/Person",
                                           "@id": 3,
                                            "identifier": user3,
                                           },
                                   "object": {
                                            "type": "https://schema.org/SportsEvent",
                                            "@id": 1
                                             }
                                           }
                                       }
                      ],
     "total_items": 2
}

400: Example Response:

{
              "message": "This event accepts participants without approval."
}

403: Example Response:

{
              "message": "Only organizers can accept users for the event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/participants DELETE - Delete Participating Status

Endpoint: /events/<event_id>/participants Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Responses:
204: "Deleted specating status"
400: Example Response:

{
              "message": "Not participanting for this event"
}

{
              "message": "Try with a valid event."
}

500:"There is an internal error, try again later."
Example Response:

{
              "error": "Try later."
}

/events/<event_id>/spectators GET - Get Spectators of Event

Endpoint: /events/<event_id>/spectators
Method: GET
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": id of the event,
    "audience": list of person schemas of the specataors
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": 1,
    "audience": [
        {
            "@context": "https://schema.org/Person",
            "@id": 3,
            "identifier": "lion"
        }
    ]
}

400: Example Response:

{
              "message": "Try with a valid event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/spectators POST - Participate as Spectator to Event

Endpoint: /events/<event_id>/spectators
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Notes:
If a users sends request to join event as spectator, that user should not have participation requests or accepted to event as participant before. If user wants to be spectator, should remove those status.
Responses:
201: "Added as spectator"
400: Example Response:

{
              "message": "Already a spectator for the event."
}

{
              "message": "Spectator capacity is full for this event."
}

{
              "message": "Registered as participant to this event, if being spectator is wanted, remove participating status."
}

{
              "message": "Showed interest to participate this event. If spectator status is wanted remove the interest."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/spectators DELETE - Delete Spectating Status

Endpoint: /events/<event_id>/spectators
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Responses:
204: "Deleted specating status"
400: Example Response:

{
              "message": "Not a spectator for this event"
}

500:"There is an internal error, try again later."
Example Response:

{
              "error": "Try later."
}

/events/<event_id>/interesteds GET - Get Interesteds of Event

Endpoint: /events/<event_id>/interesteds Method: GET
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Expected Response When No Error:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": id of the event,
    "additionalProperty" : {
                    "@type": "PropertyValue",
                    "name": "interesteds",
                    "value": list of interested users
                }
}

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": 1,
    "additionalProperty": {
                    "@type": "PropertyValue",
                    "name": "interesteds",
                    "value":[
                                     {
                                      "@context": "https://schema.org/Person",
                                      "@id": 3,
                                      "identifier": "lion"
                                       }
                              ]
                          }
}

400: Example Response:

{
              "message": "This event does not require organizer approval to participate."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/interesteds POST - Post Interest To Event

Endpoint: /events/<event_id>/interesteds Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Notes:
If a users sends interest request to join event, that user should not have participation or spectating status to event before. If user wants to be interested, should remove those status.
Responses:
201: "Added as interested"
400: Example Response:

{
              "message": "Already sent request for the event."
}

{
              "message": "Participant capacity is full for this event."
}

{
              "message": "Already participating the event."
}

{
              "message": "Registered as spectator to this event, if being participant is wanted, remove spectating status."
}

{
              "message": "No skill level is entered for the sport."
}

{
              "message": "User skill level does not match the requirements for the event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/interesteds DELETE - Delete Interested Status

Endpoint: /events/<event_id>/interesteds Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Responses:
204: "Deleted specating status"
400: Example Response:

{
              "message": "Not interested for this event"
}

500:"There is an internal error, try again later."
Example Response:

{
              "error": "Try later."
}

/events/<event_id>/badges POST - Add Badge To Event

Endpoint: /events/<event_id>/badges Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Body Parameters:

{
    "badge": name of the badge, required
}

Responses:
201: "Badge Added"
400: Example Response:

{
              "message": "Only organizers can add badges to event."
}

{
              "message": "Enter a valid badge."
}

{
              "message": "Already added this badge to event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/badges GET - Get Event Badges

Endpoint: /events/<event_id>/badges Method: GET Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Responses:
200: "Badge Added"
Example Response:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": 1,
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "event_badges",
        "value": [
            {
                "@context": "https://www.wikidata.org/entity/Q107264587",
                "name": "encouraging"
            }
        ]
    }
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/badges DELETE - Delete Event Badge

Endpoint: /events/<event_id>/badges Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

event_id: event_id of the desired event, integer.

Responses:
204: "Badge Deleted"
400: "Parameters are not correct."
Example Response:

{
              "message": "Only organizers can delete badges to event."
}

{
              "message": "Event does not exist."
}

{
              "message": "Badge does not exist."
}

{
              "message": "Badge does not exist for that event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/discussion GET - Get Event Posts

Endpoint: /events/<event_id>/discussion
Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    event_id: id of the equipment

Responses:
200: Example Response:

{
    "@context": "https://schema.org/SportsEvent",
    "@id": 1,
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "posts",
        "value": [
            {
                "@context": "https://schema.org/SocialMediaPosting",
                "@id": 2,
                "author": {
                    "@context": "https://schema.org/Person",
                    "@id": 8,
                    "identifier": "lion2"
                },
                "text": "Great event, will try to join.",
                "dateCreated": "2022-01-03T19:12:00.412002Z",
                "comment": []
            }
        ]
    }
}

400: "Parameters are not correct."
Example Response:

{
              "message": "Try with a valid event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/discussion POST - Create Event Posts

Endpoint: /events/<event_id>/discussion
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    event_id: id of the equipment

Body Parameters:

 {
             "sharedContent" : Url for an image of the event. not required
             "text" : Text of the post. required  
}

Responses:
201: Example Response:

{
    "@context": "https://schema.org/SocialMediaPosting",
    "@id": 1,
}

400: "Body parameters are not correct."
Example Response:

{
              "message": "Try with a valid event."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/discussion/<post_id> POST - Create Event Post Comment

Endpoint: /events/<event_id>/discussion/<post_id>
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    event_id: id of the event,
    post_id: id of the post to comment

Body Parameters:

 {
             "text" : Text of the comment. required  
         
}

Responses:
201:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This post does not belong to that event_id."
}

{
              "message": "Try with a valid post.."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/discussion/<post_id> DELETE - Delete Event Post

Endpoint: /events/<event_id>/discussion/<post_id>
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    event_id: id of the event,
    post_id: id of the post to comment

Responses:
204:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This post does not belong to that event_id."
}

{
              "message": "Only post authors and event creators can delete posts."
}

{
              "message": "Try with a valid discussion post."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/events/<event_id>/discussion/<post_id>/comment/<comment_id> DELETE - Delete Event Comment

Endpoint: /events/<event_id>/discussion/<post_id>/comment/<comment_id>
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    event_id: id of the event,
    post_id: id of the post,
    comment_id: id of the comment to delete

Responses:
204:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This comment does not belong to that event_id."
}

{
              "message": "This comment does not belong to that post_id."
}

{
              "message": "Only comment authors and event creators can delete posts."
}

{
              "message": "Try with a valid discussion comment."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

Activity Stream Related Endpoints

/activitystream GET - Get Activity Stream

Endpoint: /activitystream
Method: GET
Authorization: Needed.
Author: Berk Atıl
Note: We apply strategy similar to paging here. We have 2 different parameters: offset and limit. Limit represents the desired number of activity streams. Offset represents the position of the last activity stream. It means that when offset is set that activity stream will be the most recent activity. Header Parameters:

limit: total number of requested activity streams, int, required.  
offset: id of the activity stream which is the latest one (has the largest activity stream id) that will be returned, defaults to the latest activity,int, not required.

Expected Response When No Error:

{
            "@context": Context of the activity stream,
            "summary": General summary of the response object,
            "type": Type of the returned object based on scheme,
            "total_items": Total number of activities returned,
            "orderedItems": List of activities.

}

Responses:
200: "Activities are returned" Example Response:

{
            "@context": "https://www.w3.org/ns/activitystreams",
            "summary": "Activity stream",
            "type": "OrderedCollection",
            "total_items": 5,
            "orderedItems": [
                             {
                              "@context": "https://www.w3.org/ns/activitystreams",
                              "summary": f"lion1 blocked lion2",
                              "id": 5,
                              "type": "Block",
                              "actor": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 1,
                                        "identifier": "lion1"
                                     },
                              "object": {
                                         "type": "https://schema.org/Person", 
                                         "@id": 2,
                                         "identifier": "lion2"
                                        }
                             },
                             {
                              "@context": "https://www.w3.org/ns/activitystreams",
                              "summary": f"lion1 followed lion2",
                              "id": 4,
                              "type": "Follow",
                              "actor": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 1,
                                        "identifier": "lion1"
                                     },
                              "object": {
                                         "type": "https://schema.org/Person", 
                                         "@id": 2,
                                         "identifier": "lion2"
                                        }
                             },
                              {
                              "@context": "https://www.w3.org/ns/activitystreams",
                              "summary": f"lion1 created let's play",
                              "id": 3,
                              "type": "Create",
                              "actor": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 1,
                                        "identifier": "lion1"
                                     },
                              "object": {
                                         "type": "https://schema.org/Event", 
                                         "@id": 1,
                                         "name": "let's play"
                                        }
                             },
                             {
                              "@context": "https://www.w3.org/ns/activitystreams",
                              "summary": f"lion1 accepted lion2 for let's play",
                              "id": 2,
                              "type": "Accept",
                              "actor": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 1,
                                        "identifier": "lion1"
                                     },
                              "object": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 2,
                                        "identifier": "lion2"
                                     },
                              "target": {
                                         "type": "https://schema.org/Event", 
                                         "@id": 1,
                                         "name": "let's play"
                                        }
                             },
                               {
                              "@context": "https://www.w3.org/ns/activitystreams",
                              "summary": f"lion1 joins to let's play as a spectator",
                              "id": 3,
                              "type": "Activity",
                              "actor": {
                                        "type": "https://schema.org/Person", 
                                        "@id": 1,
                                        "identifier": "lion1"
                                     },
                              "target": {
                                         "type": "https://schema.org/Event", 
                                         "@id": 1,
                                         "name": "let's play"
                                        }
                             },
                            ]
}

Badge Related Endpoints

/badges GET - Get System Badges

Endpoint: /badges
Method: GET
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Expected Response When No Error:

{
    "badges": [
              list of badges, contains context if wikidata badge
              ]
}

Responses:
200:
Example Response:

{
    "badges": [
        {
            "@context": "https://www.wikidata.org/entity/Q484275",
            "name": "leadership"
        },
        {
            "name": "good supporter"
        }
    ]
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/badges POST - Request New Badges

Endpoint: /badges
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Body Parameters:

{
    "sport": Related sport. not required
    "description": Request description. required
}

Responses:
201:
500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/badges/<sport_name> GET - Get Sport Related Badges

Endpoint: /badges/<sport_name>
Method: POST
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    sport_name: name of the sport to get the badges

Responses:
200: Example Response:

{
    "badges": [
        {
            "name": "football supporter",
            "@context": "https://www.wikidata.org/entity/Q3504889",
            "sport": "soccer"
        },
        {
            "name": "freekick master",
            "sport": "soccer"
        }
    ]
}

400:"Wrong path parameter."
Example Response:

{
              "message": "Enter valid sport."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

Equipment Related Endpoints

/equipments POST - Create Equipment

Endpoint: /equipments
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Body Parameters:
latitude and longitude should be given together if given.

 {
             "name" : Name of the equipment, required
             "sport" : Sport related to equipment, must be one of the sports on the system. required
             "description" : A description of the equipment. not required
             "sharedContent" : Url for an image of the equipment. not required
             "latitude" : Latitude of the equipment. required  
             "longitude" : Longitude of the equipment. required  
             
}

Responses:
201: "Equipment created."
Example Response:

{
              "@context": 'https://schema.org/Product',
              "@id": 1
}

400: "Body parameters are not correct."
Example Response:

{
              "message": "Enter a valid sport."
}

500:"There is an internal error, try again later."

{
              "error": "There is an internal error, try again later."
}

/equipments/<equipment_id> GET - Get Equipment

Endpoint: /equipments/<equipment_id>
Method: GET
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment

Responses:
200:
Example Response:

{
    "@context": "https://schema.org/Product",
    "@id": 1,
    "name": "equipment post",
    "sport": {
        "@type": "Thing",
        "name": "soccer"
    },
    "geo": {
        "@type": "GeoCoordinates",
        "latitude": 41.002697,
        "longitude": 39.716763
    },
    "description": "",
    "additionalProperty": [
        {
            "@type": "PropertyValue",
            "name": "created_on",
            "value": "2022-01-02T10:27:48.399761Z"
        }
    ],
    "creator": {
        "@type": "Person",
        "@id": 1,
        "identifier": "lion2"
    }
}

400: "Body parameters are not correct."
Example Response:

{
              "message": "Equipment id does not exist."
}

500:"There is an internal error, try again later."

{
              "error": "An error occured, please try again later."
}

/equipments/<equipment_id> DELETE - Delete Equipment

Endpoint: /equipments/<equipment_id>
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment

Responses:
204:
400: "Body parameters are not correct."
Example Response:

{
              "message": "Try with a valid equipment."
}

403: "Only creators can delete equipments."
Example Response:

{
              "message": "Only creators can delete equipments."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/<equipment_id>/discussion GET - Get Equipment Posts

Endpoint: /equipments/<equipment_id>/discussion
Method: GET
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment

Responses:
200: Example Response:

{
    "@context": "https://schema.org/Product",
    "@id": 1,
    "additionalProperty": {
        "@type": "PropertyValue",
        "name": "posts",
        "value": [
            {
                "@context": "https://schema.org/SocialMediaPosting",
                "@id": 1,
                "sharedContent": "https://google.com",
                "author": {
                    "@context": "https://schema.org/Person",
                    "@id": 1,
                    "identifier": "lion2"
                },
                "text": "hey",
                "dateCreated": "2022-01-02T10:28:49.692598Z",
                "comment": [
                    {
                        "@context": "https://schema.org/Comment",
                        "@id": 1,
                        "author": {
                            "@context": "https://schema.org/Person",
                            "@id": 1,
                            "identifier": "lion2"
                        },
                        "text": "I agree",
                        "dateCreated": "2022-01-02T10:29:21.031934Z"
                    }
                ]
            }
        ]
    }
}

400: "Body parameters are not correct."
Example Response:

{
              "message": "Try with a valid equipment."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/<equipment_id>/discussion POST - Create Equipment Posts

Endpoint: /equipments/<equipment_id>/discussion
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment

Body Parameters:

 {
             "sharedContent" : Url for an image of the equipment. not required
             "text" : Text of the post. required  
         
}

Responses:
201: Example Response:

{
    "@context": "https://schema.org/SocialMediaPosting",
    "@id": 1,
}

400: "Body parameters are not correct."
Example Response:

{
              "message": "Try with a valid equipment."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/<equipment_id>/discussion/<post_id> POST - Create Equipment Post Comment

Endpoint: /equipments/<equipment_id>/discussion/<post_id>
Method: POST
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment,
    post_id: id of the post to comment

Body Parameters:

 {
             "text" : Text of the comment. required  
         
}

Responses:
201:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This post does not belong to that equipment_id."
}

{
              "message": "Try with a valid post.."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/<equipment_id>/discussion/<post_id> DELETE - Delete Equipment Post

Endpoint: /equipments/<equipment_id>/discussion/<post_id>
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment,
    post_id: id of the post to comment

Responses:
204:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This post does not belong to that equipment_id."
}

{
              "message": "Only post authors and equipment creators can delete posts."
}

{
              "message": "Try with a valid discussion post."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/<equipment_id>/discussion/<post_id>/comment/<comment_id> DELETE - Delete Equipment Comment

Endpoint: /equipments/<equipment_id>/discussion/<post_id>/comment/<comment_id>
Method: DELETE
Authorization: Needed
Author: Elif Sema Balcıoğlu
Path Parameters:

    equipment_id: id of the equipment,
    post_id: id of the post,
    comment_id: id of the comment to delete

Responses:
204:

400: "Body parameters are not correct."
Example Response:

{
              "message": "This comment does not belong to that equipment_id."
}

{
              "message": "This comment does not belong to that post_id."
}

{
              "message": "Only comment authors and equipment creators can delete posts."
}

{
              "message": "Try with a valid discussion comment."
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

/equipments/searches POST - Search Equipment

Endpoint: /equipments/searches
Method: POST
Authorization: Not Needed
Author: Elif Sema Balcıoğlu
Body Parameters:
End and start for latitude and longitude must be given together

 {
             "creator" : Url for an image of the equipment. not required
             "nameContains" : Text of the post. not required  
             "latitudeBetweenStart": Start latitude. not required
             "latitudeBetweenEnd": End latitude. not required
             "longitudeBetweenStart": Start longitude. not required
             "longitudeBetweenEnd": End longitude. not required
             "sport": Sport of the equipment. not required       
}

Responses:
200:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "OrderedCollection",
    "total_items": 1,
    "items": [
        {
            "@context": "https://schema.org/Product",
            "@id": 1,
            "name": "equipment post",
            "sport": {
                "@type": "Thing",
                "name": "soccer"
            },
            "geo": {
                "@type": "GeoCoordinates",
                "latitude": 41.002697,
                "longitude": 39.716763
            },
            "description": "",
            "additionalProperty": [
                {
                    "@type": "PropertyValue",
                    "name": "created_on",
                    "value": "2022-01-02T10:27:48.399761Z"
                }
            ],
            "creator": {
                "@type": "Person",
                "@id": 1,
                "identifier": "lion2"
            }
        }
    ]
}

400: "Body parameters are not correct."
Example Response:

{
    "message": {
        "latitudeBetweenStart": [
            "A valid number is required."
        ]
    }
}

500:"There is an internal error, try again later."

{
              "error": "Try later."
}

Notification Related Endpoints

/notifications GET - Get Notifications

Endpoint: /notifications
Method: GET
Authorization: Needed.
Author: Berk Atıl

Header Parameters:

Authorization: Token <Token of the user>

Expected Response When No Error:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "summary": "Notifications",
    "type": "Collection",
    "total_items": 2,
    "items": [
      {
            "description": "The spectator capacity for the event with name let's play is full now.",   
            "notification_id": 1,  
            "event_id": 1,  
            "date": "2021-12-31T13:00:00",
            "type": "Event Full"
    },
    {
            "description": "1 Day Left for the event with name let's cycle that you will participate",
            "notification_id": 2,  
            "event_id": 4,  
            "date": "2022-01-31T13:00:00",
            "type": 1 Day Left"
    },
    ]
}

Responses:
200: "Notifications are returned" Example Response:

{
    "@context": "https://www.w3.org/ns/activitystreams",
    "summary": "Notifications",
    "type": "Collection",
    "total_items": 2,
    "items": [
      {
            "description": "The spectator capacity for the event with name let's play is full now.",   
            "notification_id": 1,  
            "event_id": 1,  
            "date": "2021-12-31T13:00:00",
            "type": "Event Full"
    },
    {
            "description": "1 Day Left for the event with name let's cycle that you will participate",
            "notification_id": 2,  
            "event_id": 4,  
            "date": "2022-01-31T13:00:00",
            "type": 1 Day Left"
    },
    ]
}

401: "Invalid token."
Example Response:

{
    "message": "Login required."
}

500:"There is an internal error, try again later."

{
    "message": "Try later."
}

/notifications/<notification_id> POST - Read Notification

Endpoint: /notifications/<notification_id>
Method: POST
Authorization: Needed.
Author: Berk Atıl

Path Parameters:

notification_id: notification_id of the desired notification, integer.

Header Parameters:

Authorization: Token <Token of the user>

Responses:
200: "Notification is read" 400: "Notification does not exist.."
Example Response:

{
              "message": "Notification does not exist."
}

401: "Invalid token."
Example Response:

{
    "message": "Login required."
}

403: "Not allowed to read notifications of another user."

{
    "message": "Not allowed to read notifications of another user."
}

500:"There is an internal error, try again later."

{
    "message": "Try later."
}

Recommendation Related Endpoints

/recommendations GET - Get Recommendations

Endpoint: /recommendations
Method: GET
Authorization: Needed.
Author: Berk Atıl

Header Parameters:

Authorization: Token <Token of the user>

Expected Response When No Error:

[
     {       
      "event_id": Id of the event.
      "name": Name of the event.  
      "sport": Sport type of the event.       
      "organizer": Organizer of the event.    
      "description": Description of the event.   
      "startDate": Date of the event.   
      "additionalProperty": Additional information about the event.   
      "latitude": Latitude of the event location.  
      "longitude": Longitude of the event location.    
      "city": City of the event.     
      "district": District of the event.  
      "country": Country of the event.   
      "minimumAttendeeCapacity": Minimum participants that must attend to the event.      
      "maximumAttendeeCapacity": Maximum participants that can attend to the event. 
      "maxSpectatorCapacity": Maximum spectators that should attend to the event. 
      "minSkillLevel": Minimum skill level required for the event.    
      "maxSkillLevel": Maximum skill level required for the event.
      "acceptWithoutApproval": Boolean to indicate if approval is needed to participate.  
      "canEveryonePostPosts": Boolean to indicate if everyone can post posts to the event.    
      "duration": Duration of the event.  
      "created_on": Creation date of the event.
   }
]

Responses:
200: "Recommended events are returned" Example Response:

[
 {       
      "event_id": 2,  
      "name": "play soccer",  
      "sport": "soccer",       
      "organizer": 12,     
      "description": "",  
      "startDate": "2022-01-31T13:00:00",    
      "latitude": 38.2331,  
      "longitude": 32.2345,      
      "city": "Istanbul",     
      "district": "Sariyer",   
      "country": "Turkey",    
      "minimumAttendeeCapacity": 2,        
      "maximumAttendeeCapacity": 10,   
      "maxSpectatorCapacity": 45, 
      "minSkillLevel": 3,    
      "maxSkillLevel": 4,    
      "acceptWithoutApproval": True,    
      "canEveryonePostPosts": True,  
      "duration": 60,   
      "created_on": "2021-12-31T13:00:00",  
   }
]

401: "Invalid token."
Example Response:

{
    "message": "Login required."
}

500:"There is an internal error, try again later."

{
    "message": "Try later."
}
⚠️ **GitHub.com Fallback** ⚠️