Home for Students APIs

# Home for Students APIs ## Frontoffice All the endpoints below are internazionalized and they are scoped by language. Currently, the handled languages are `it` and `en`. ### POST /api/v1/contact-forms Used to create a new message. ##### Body ```json { email: string, subject: string, body: string, name: string, } ``` ### POST api/v1/newsletters Used to subscribe a user to the Mailchimp newsletter. #### Body ```json { locationType: 'city' | 'area' | 'interest-point', locationUuid: string, email: string, name: string, } ``` ### GET /api/v1/search/locations Returns all the locations entities like cities, cities' areas and interest points. #### Query params | Name | Description | Type | Default value | | -------- | --------------------------------- | -------- | -------------- | | page | Current page of results | number | 0 | | q | Query term | string | <empty string> | | results | Number of results of current page | number | 5 | | types | Types of locations | string[] | null | #### Results ```typescript { type: 'city' | 'area' | 'interest-point' | 'tag' name: string, uuid: string, }[] ``` ### GET /api/v1/search/rooms Returns all rooms that respect the requested filter #### Query params | Name | Description | Type | Default value | Required | | ---------- | --------------------------------- | --------- | ------------- | -------- | | entityType | Type of the requested location entity | 'city', 'area', 'interest-point' | city | no | | entityUuid | UUID of the requested location entity | string | - | no | | checkIn | Date of check in | isoDate | null | no | | checkOut | Date of check out| isoDate | null | no | | roomType | Searched room type | 'single', 'double' | null | no | | page | Requested page of types | number | 0 | no | | results | Number of results for the current page | number | 5 | no | #### Results ```typescript { houseAddress: string, houseDescription: string, photos: { alt?: string, src: string, }[], price: number, // NOTE: It should be sent formatted as an integer uuid: string, }[] ``` # Backoffice ### POST /api/v1/users/auth Permit to authenticate a user. #### Body - email: string - password: string #### Response ```json { token: string } ``` ### GET /api/v1/self/me Permit to retrieve properties regarding the current user. #### Headers - Authentication: bearer <jwt_token> #### Response ```json { role: 'admin' | 'office' | 'customer' } ``` ## Language ### GET /api/v1/languages Retrieve all the available languages. #### Response ```typescript= { code: string isDefault: boolean name: string uuid: string }[] ``` ## Area ### GET /api/v1/area/:areaUuid/translations Retrieve all the translations of an area. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript { description: string languageUuid: string name: string status: string[] // e.g. deletable, modifiable uuid: string }[] ``` ### PUT /api/v1/area/:areaUuid/translations/:translationUuid Modify the translation of an area. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { name: string description: string } ```  ## House Common Zone ### GET /api/v1/house-common-zones Get house common zones list. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { createdAt: string defaultTranslation: { description: string name: string uuid: string } icon: string updatedAt: string uuid: string }[] ``` ### POST /api/v1/house-common-zones Create new house common zone. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { icon: string translation: { name: string description: string } } ``` #### Response ```typescript= { uuid: string, icon: string translations: { uuid: string, houseCommonZoneUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] } ``` ### GET /api/v1/house-common-zones/:houseCommonZoneUuid Get house common zone data. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, icon: string createdAt: isoDate, updatedAt: isoDate }[] ``` ### GET /api/v1/house-common-zones/:houseCommonZoneUuid/translations Get house common zone translations. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, houseCommonZoneUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### PUT /api/v1/house-common-zones/:houseCommonZoneUuid/translations/:translationUuid Modify the translation of a house common zone. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { name?: string description?: string } ``` #### Response ```typescript= { description: string name: string languageUuid: string houseCommonZoneUuid: string uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ## House Service ### GET /api/v1/house-services Get house services list. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript { createdAt: string defaultTranslation: { description: string name: string uuid: string } icon: string updatedAt: string uuid: string }[] ``` ### POST /api/v1/house-services Create new house service. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { icon: string translation: { name: string description: string } } ``` #### Response ```typescript= { uuid: string, icon: string translations: { uuid: string, houseServiceUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] } ``` ### GET /api/v1/house-services/:houseServiceUuid Get house service data. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, icon: string createdAt: isoDate, updatedAt: isoDate }[] ``` ### GET /api/v1/house-services/:houseServiceUuid/translations Get house service translations. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, houseServiceUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### PUT /api/v1/house-services/:houseServiceUuid/translations/:translationUuid Modify the translation of a house service. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { name?: string description?: string } ``` #### Response ```typescript= { description: string name: string languageUuid: string houseServiceUuid: string uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ## Interest Points ### GET /api/v1/interest-points Get the list of interest points. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript { uuid: string, areaUuid: string, latitude: numeric, longitude: numeric, address: string, createdAt: string, updatedAt: string }[] ``` ### POST /api/v1/interest-points Create a new interest point. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { uuid: string areaUuid: string latitude: number longitude: number address: string translation: { name: string description: string } } ``` #### Response ```typescript= { uuid: string, areaUuid: string latitude: number longitude: number address: number createdAt: isoDate, updatedAt: isoDate translations: { uuid: string, tagUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] } ``` ### GET /api/v1/interest-points/:interestPointsUuid Get interest points data. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, areaUuid: string latitude: number longitude: number address: number createdAt: isoDate, updatedAt: isoDate }[] ``` ### GET /api/v1/interest-points/:interestPointsUuid/translations Get interest points translations. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, interestPointUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### PUT /api/v1/interest-points/:interestPointsUuid/translations/:translationUuid Modify the translation of a interest point. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { name?: string description?: string } ``` #### Response ```typescript= { description: string name: string languageUuid: string interestPointUuid: string uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ## Photos ### DELETE /api/v1/photos/:uuid Delete a photo from the DB the the S3 bucket. #### Headers - Authentication: bearer <jwt_token> ## Room ### GET /api/v1/aggregate/rooms/:uuid/photos Get the photos of a room. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript { alt: string createdAt: string mimetypes: ('image/jpeg' | 'image/webp')[] uuid: string }[] ``` ### POST /api/v1/rooms/:uuid/photos Create a new photo. #### Headers - Authentication: bearer <jwt_token> #### Body ``` FormData { alt: string photo: ByteArray } ``` ## Tag ### GET /api/v1/tags Get tags list. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript { uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### POST /api/v1/tags Create new Tag. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { translation: { name: string description: string } } ``` #### Response ```typescript= { uuid: string, createdAt: isoDate, updatedAt: isoDate translations: { uuid: string, tagUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] } ``` ### GET /api/v1/tags/:tagUuid Get tag data. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### GET /api/v1/tags/:tagUuid/translations Get tag translations. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { uuid: string, tagUuid: string, languageUuid: string, name: string, description: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ### PUT /api/v1/tags/:tagUuid/translations/:translationUuid Modify the translation of a tag. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { name?: string description?: string } ``` #### Response ```typescript= { description: string name: string languageUuid: string tagUuid: string uuid: string, createdAt: isoDate, updatedAt: isoDate }[] ``` ## Reservations ```typescript= ReservationStatus { activated = 'activated', canceled = 'canceled', charging = 'charging', checking = 'checking', expired = 'expired', failed = 'failed', pending = 'pending', refunded = 'refunded', } ``` ### GET /api/v1/aggregate/reservations Get aggregate reservations. #### Headers - Authentication: bearer <jwt_token> #### Query params | Name | Description | Type | Default value | | ------------ | --------------------------------- | ------------------- | -------------- | | customerUuid | customer that do reservation | uuid | null | | endDate | End date filter | Date | null | | page | Current page of results | number | 0 | | paymentType | Type of payment | `internal`\|`stripe` | null | | results | Number of results of current page | number | 5 | | roomUuid | room reserved | uuid | null | | startDate | Start Date filter | Date | null | | status | Reservation status | ReservationStatus | null | #### Response ```typescript= { customerUuid: string deletedAt: Date | undefind depositPrice: number endDate: Date price: number roomUuid: string startDate: Date status: ReservationStatus uuid: string customer: { deletedAt: Date | undefind email: string firstName: string lastName: string phone: string uuid: string } room: { active: boolean creatorUuid: string depositPrice: number description: string electricityBill: boolean gasBill: boolean house: { uuid: string areaUuid: string creatorUuid: string address: string area: { cityUuid: string city: { description: string name: string uuid: string } description: string name: string uuid: string } } houseUuid: string internetBill: boolean monthPrice: number name: string roomType: 'double' | 'shared' | 'single', size: number uuid: string waterBill: boolean } payment:{ deletedAt: Date | undefind type: 'internal' | 'stripe' paymentId: string reservationUuid: string uuid: string } }[] ``` ### GET /api/v1/aggregate/reservations/:reservationUuid Get aggregate reservation. #### Headers - Authentication: bearer <jwt_token> #### Response ```typescript= { customerUuid: string deletedAt: Date | undefind depositPrice: number endDate: Date price: number roomUuid: string startDate: Date status: ReservationStatus uuid: string customer: { deletedAt: Date | undefind email: string firstName: string lastName: string phone: string uuid: string } room: { active: boolean creatorUuid: string depositPrice: number description: string electricityBill: boolean gasBill: boolean house: { uuid: string areaUuid: string creatorUuid: string address: string area: { cityUuid: string city: { description: string name: string uuid: string } description: string name: string uuid: string } } houseUuid: string internetBill: boolean monthPrice: number name: string roomType: 'double' | 'shared' | 'single', size: number uuid: string waterBill: boolean } payment:{ deletedAt: Date | undefind type: 'internal' | 'stripe' paymentId: string reservationUuid: string uuid: string } } ``` ### PATCH /api/v1/aggregate/reservations/:reservationUuid/period Get aggregate reservation. #### Headers - Authentication: bearer <jwt_token> #### Body ```typescript= { endDate: isoDate startDate: isoDate } ``` #### Response ```typescript= { customerUuid: string deletedAt: Date | undefind depositPrice: number endDate: Date price: number roomUuid: string startDate: Date status: ReservationStatus uuid: string } ``` ## Payments