Houses API Documentation

API Endpoint
http://localhost:5000/v1/api

HouseAPI is an API service allowing analyst to query housing houses data.

Allowed HTTP requests: 

POST    : Update resource
GET     : Get a resource or list of resources

Description Of Usual Server Responses:

  • 200 OK - the request was successful (some API calls may return 201 instead).

  • 201 Created - the request was successful and a resource was created.

  • 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).

  • 400 Bad Request - the request could not be understood or was missing required parameters.

  • 401 Unauthorized - authentication failed or user doesn’t have permissions for requested operation.

  • 403 Forbidden - access denied.

  • 404 Not Found - resource was not found.

Houses

Represents House Details

House attributes:

  • _id (String)) : unique identifier, the house_id in url

  • title (String(20)) : e.g. 吉屋

  • city (String(6)) : e.g. 桃園市

  • district (String(6)) : e.g. 中和區

  • lessor (String(10)) : e.g. 王先生

  • lessor_gender (String(2)) : optional. e.g. 男

  • lessor_identity (String(10)) : e.g. 代理人

  • house_type (String(10)) : optional. e.g. 公寓

  • house_status (String(20)) : e.g. 雅房

  • sold (String(15)) : optional. e.g. 3天成交

  • phone (String(20)) : optional. e.g. 09xxxxxxxx

  • gender_requirement (String(15)) : optional. e.g. 男女生皆可

  • house_condition (String) : Hash identifier. e.g. 正常

House Collection

GET http://localhost:5000/v1/api/houses
Requestsexample 1example 2example 3

success

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Responses200404
Headers
Content-Type: application/json
Body
{
    "message": "not found",
    "len": 1,
    "data": [
        {
            "_id": "10362106",
            "title": "天母SOGO套房",
            "city": "台北市",
            "district": "士林區",
            "lessor": "許小姐",
            "lessor_gender": "女",
            "lessor_identity": "代理人",
            "house_type": "公寓",
            "house_status": "獨立套房",
            "sold": "",
            "phone": "09********",
            "gender_requirement": "男女生皆可",
            "house_condition": "乾淨明亮精緻套房"
        },
    ]
}
Headers
Content-Type: application/json
Body
{
  "message": "not found",
  "len": 0,
  "data": []
}

without token

Headers
Content-Type: application/json
Responses400
Headers
Content-Type: application/json
Body
{
  "message": {
    "Authorization": "Missing required parameter in the HTTP headers"
  }
}

wrong token

Headers
Content-Type: application/json
Authorization: wrongtoken
Responses401
Headers
Content-Type: application/json
Body
{
  "message": "Invalid token"
}

List all houses
GET/houses

POST http://localhost:5000/v1/api/houses
Requestsexample 1example 2example 3

success

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
    "house_id": "11111117",
    "title": "吉屋",
    "city": "桃園市",
    "district": "中和區",
    "lessor": "王先生",
    "lessor_identity": "代理人",
    "house_type": "公寓",
    "house_status": "雅房",
    "sold": None,
    "phone": "09xxxxxxxx",
    "gender_requirement": "男女生皆可",
    "house_condition": "正常",
}
Responses201
Headers
Content-Type: application/json
Location: /houses/11111117
Body
{
  "data": null
}

without token

Headers
Content-Type: application/json
Responses400
Headers
Content-Type: application/json
Body
{
  "message": {
    "Authorization": "Missing required parameter in the HTTP headers"
  }
}

wrong token

Headers
Content-Type: application/json
Authorization: wrongtoken
Responses401
Headers
Content-Type: application/json
Body
{
  "message": "Invalid token"
}

Create a House
POST/houses

Houses Collection

House objects with all their details

GET http://localhost:5000/v1/api/houses/?renter_gender=男&city=新北市&district=三重區&house_type=公寓&house_status=分租套房&phone=09********&lessor_identity=屋主&lessor_gender=男&lessor_lastname=吳&explain=on
Responses200404

use /houses?city=新北市&district=三重區&lessor_identity=非屋主&lessor_gender=男 will return

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
    "message": "success",
    "len": 1,
    "data": [
        {
            "_id": "10784563",
            "title": "永福街全新精美套房",
            "city": "新北市",
            "district": "三重區",
            "lessor": "郭先生",
            "lessor_gender": "男",
            "lessor_identity": "代理人",
            "house_type": "公寓",
            "house_status": "獨立套房",
            "sold": "",
            "phone": "09********",
            "gender_requirement": "男女生皆可",
            "house_condition": "✅租金包水費、網路，第四台，電5元"
        },
    ]
}

use /houses?city=台北市&district=三重區 will return

Headers
Content-Type: application/json
Body
{
  "message": "not found",
  "len": 0,
  "data": []
}

Retrieve Houses with conditions
GET/houses/{?renter_gender,city,district,house_type,house_status,phone,lessor_identity,lessor_gender,lessor_lastname,explain}

URI Parameters
HideShow
renter_gender
String (optional) Example: 男

Set to 男 to retrieve data with gender requirement equal to “男生” or “男女生皆可”

Choices: 男 女

city
String (optional) Example: 新北市

use ?city=新北市 <= Return data Group which city = 新北市

Choices: 台北市 新北市

district
String (optional) Example: 三重區

user ?district=三重區 <= Return data Group which district = “三重區”

house_type
String (optional) Example: 公寓

Set to 公寓 to retrieve house type equal to 公寓

house_status
String (optional) Example: 分租套房

Set to 分租套房 to retrieve house status equal to 公寓

phone
String (optional) Example: 09********

use ‘?phone=hour’ <= Return data Group which phone = “09********”

lessor_identity
String (optional) Example: 屋主

Set to 屋主 to retrieve lessor identity equal to 屋主

Choices: 屋主 代理人 非屋主 仲介

lessor_gender
String (optional) Example: 男

Set to 男 to retrieve lessor gender equal to 男

Choices: 男 女

lessor_lastname
String (optional) Example: 吳

retrieve

explain
String (optional) Example: on

use ‘?explain=on’ <= Return the query plan and execution detail

Choices: on

Accounts

Represents Accounts Details

Account attributes:

  • username (Number(10)) : Require, unique identifier.

  • user_role (String(5)) : Require. “admin” or “user”

  • token (String(32)) : Require. api users sould attach token in header when calling api

  • month_api_limit (Number) : Require. the maximum API calling limit in one month

  • api_quota (Number) : Require. the remain api calling quota of this month

  • key_expire_at (Date) : Require. the expiry date of token

Account Collection

POST http://localhost:5000/v1/api/accounts
Requestsexample 1example 2example 3example 4example 5example 6

new username

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
    "username": "api-admin",
    "user_role": "admin",
}
Responses201
Headers
Content-Type: application/json
Body
{
  "message": "success",
  "data": {
    "username": "api-admin",
    "user_role": "admin",
    "token": "60cb6dd5b71d4e13a2270ba384fb779f",
    "month_api_limit": 5000,
    "api_quota": 5000,
    "key_expire_at": "2022-06-07T15:42:44"
  }
}

username is already taken

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
    "username": "api-admin",
    "user_role": "admin",
}
Responses400
Headers
Content-Type: application/json
Body
{
  "message": "username exists"
}

no user_role

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
  "username": "api-admin"
}
Responses400
Headers
Content-Type: application/json
Body
{
  "message": {
    "user_role": "need to add user_role to storage"
  }
}

wrong user_role

Headers
Content-Type: application/json
Authorization: 2bb431e67cc9481dafb6af689e35ddb9
Body
{
    "username": "api-admin",
    "user_role": "super",
}
Responses400
Headers
Content-Type: application/json
Body
{
  "message": "invalid user_role"
}

without token

Headers
Content-Type: application/json
Responses400
Headers
Content-Type: application/json
Body
{
  "message": {
    "Authorization": "Missing required parameter in the HTTP headers"
  }
}

wrong token

Headers
Content-Type: application/json
Authorization: wrongtoken
Responses401
Headers
Content-Type: application/json
Body
{
  "message": "Invalid token"
}

Create a Account
POST/accounts

Generated by aglio on 22 Jun 2021