APIs Related to Room Management

As the smallest unit structure of equipment installation, the room is the maximum range of equipment linkage.

API List

Request method	API	description
POST	/v1.0/osaas/projects/{project_id}/room	API for Adding a Room
PUT	/v1.0/osaas/rooms/{room_id}/ownership	API for Room ownership transfer
GET	/v1.0/osaas/projects/{project_id}/rooms	API for Querying the Room List
GET	/v1.0/osaas/rooms/{room_id}	API for Obtaining Room Details
PUT	/v1.0/osaas/rooms/{room_id}	API for Modifying Room Information
DELETE	/v1.0/osaas/rooms/{room_id}	API for Deleting a Room
GET	/v1.0/osaas/rooms/{room_id}/construction/status	API for Obtaining Room Construction Status
GET	/v1.0/osaas/projects/{project_id}/spaces	API for Querying the Room List (Contains Public Areas)

APIs Related to Room Management

API Description

You can use this API to add a room based on the unique ID of a project and room information. The room number in a space must be unique.

API Address

POST /v1.0/osaas/projects/{project_id}/room

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
space_id	String	BODY	Unique ID of a space. It indicates the space to which a room belongs and is used as required.	No
room_name	String	BODY	Room name, which contains a maximum of 64 characters.	Yes
room_no	String	BODY	Room number, which contains a maximum of 32 characters.	Yes
telephone	String	BODY	Phone number, which contains a maximum of 20 characters.	No
description	String	BODY	Description about a room, which contains a maximum of 255	No
uid	String	BODY	You can specify the unique ID of APP users to create houses for APP users	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	String	Unique ID of a room.

Request Example

POST {url}/v1.0/osaas/projects/1160823965053******/room

{
  "room_no": "101",
  "room_name": "Test Room",
  "space_id": "11608239650531******"
}

Success Response Example

{
  "success": true,
  "result": "11123823965053******",
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Room ownership transfer

API Description

You can use this API to transfer the ownership of the room to the APP user.

API Address

PUT /v1.0/osaas/rooms/{room_id}/ownership

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes
uid	String	BODY	Unique ID of a APP user.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Result object.

Request Example

PUT {url}/v1.0/osaas/rooms/12809159*******/ownership

{
  "uid": "ay2213******"
}

Success Response Example

{
  "success": true,
  "result": "11123823965053*******",
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying the Room List

API Description

You can use this API to query the room list based on the unique ID of a project.

API Address

GET /v1.0/osaas/projects/{project_id}/rooms

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
page_no	Integer	URL	Page number.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100.	No
room_ids	String[]	URL	List of room IDs, which contains a maximum of 100 room IDs.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code. Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message. It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
rooms	Arrays	Room set.

Parameters in rooms

Parameter	Type	Description
room_id	String	Unique ID of a room.
room_name	String	Room name.
room_no	String	Room number.
telephone	String	Phone number.
construction_status	String	Construction status of a room. The values are as follows: UNAUTHORIZED: unauthorized PENDING_CONSTRUCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
gmt_create	Long	Creation time, which is a 13-digit timestamp
gmt_modified	Long	Modification time, which is a 13-digit timestamp

Request Example

GET {url}/v1.0/osaas/projects/1160823965053******/rooms

Success Response Example

{
  "result": {
    "total": 1,
    "page_no": 1,
    "page_size": 10,
    "rooms": [
      {
        "room_id": "11608239650******",
        "room_name": "Test Room",
        "room_no": "1001",
        "description": "Room description",
        "construction_status": "UNAUTHORIZED",
        "gmt_create": 1559707046000,
        "gmt_modified": 1559707046000
      }
    ]
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Room Details

API Description

You can use this API to obtain room details based on the unique ID of the room.

API Address

GET /v1.0/osaas/rooms/{room_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object

Parameters in result

Parameter	Type	Description
room_id	String	Unique ID of a room.
room_name	String	Room name.
room_no	String	Room number.
telephone	String	Phone number
construction_status	String	Construction status of a room. The values are as follows: UNAUTHORIZED: unauthorized PENDING_CONSTRUCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted
gmt_create	long	Creation time, which is a 13-digit timestamp.
gmt_modified	long	Modification time, which is a 13-digit timestamp.

Request Example

GET {url}/v1.0/osaas/rooms/116082396505314xxxxx

Success Response Example

{
  "result": {
    "room_id": "1160823965053******",
    "project_id": "1123999444650*******",
    "room_name": "Test Room",
    "room_no": "1001",
    "description": "Room description",
    "construction_status": "UNAUTHORIZED",
    "gmt_create": 1559707046000,
    "gmt_modified": 1559707046000
  },
  "success": true,
  "t": 1561381210234
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Modifying Room Information

API Description

You can use this API to modify information about a room based on the unique ID of the room. The room number must be unique.

API Address

PUT /v1.0/osaas/rooms/{room_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes
room_name	String	BODY	Room name, which contains a maximum of 64 characters.	No
room_no	String	BODY	Room number, which contains a maximum of 32 characters.	No
telephone	String	BODY	Phone number, which contains a maximum of 20 characters.	No
description	String	BODY	Description about a room, which contains a maximum of 255 characters.	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

PUT {url}/v1.0/osaas/rooms/116082396505******

{
  "room_no": "101",
  "room_name": "Test Room"
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Deleting a Room

API Description

You can use this API to delete a room based on the unique ID of the room.

API Address

DELETE /v1.0/osaas/rooms/{room_id}

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code. Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message. It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

DELETE {url}/v1.0/osaas/rooms/116082396505314xxxxx

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Obtaining Room Construction Status

API Description

You can use this API to obtain room construction status based on the unique ID of the room.

API Address

GET /v1.0/osaas/rooms/{room_id}/construction/status

Request Parameters

Parameter	Type	Position	Description	Mandatory
room_id	String	URI	Unique ID of a room	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	String	Construction status of a room. The values are as follows: UNAUTHORIZED: unauthorized PENDING_CONSTRUCTION: to be constructed IN_CONSTRUCTION: being constructed PENDING_ACCEPTANCE: to be accepted ACCEPTANCE_COMPLETE: accepted

Request Example

GET {url}/v1.0/osaas/rooms/116082396505******/construction/status

Success Response Example

{
  "success": true,
  "result": "UNAUTHORIZED",
  "t": 1566053034624
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

API for Querying the Room List (Contains Public Areas)

API Description

You can use this API to query the room list based on the unique ID of a project.

API Address

GET /v1.0/osaas/projects/{project_id}/spaces

Request Parameters

Parameter	Type	Position	Description	Mandatory
project_id	String	URI	Unique ID of a project.	Yes
page_no	Integer	URL	Page number.	No
page_size	Integer	URL	Number of records on a page, which is greater than 0 and less than 100.	No
parent_space_id	String	URL	Parent space id (if not passed, the default is to query the first-level space under the project)	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code. Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message. It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
total	Integer	Total number of records.
page_no	Integer	Page number.
page_size	Integer	Number of records on a page.
spaces	Arrays	Room set.

Parameters in spaces

Parameter	Type	Description
space_id	String	Unique ID of a room.
space_name	String	Room name.
space_type	String	Room type.
sort	Integer	sort
gmt_create	Long	Creation time, which is a 13-digit timestamp
gmt_modified	Long	Modification time, which is a 13-digit timestamp

Request Example

GET {url}/v1.0/osaas/projects/1160823965053******/spaces

Success Response Example

{
    "result": {
        "page_no": 1,
        "page_size": 10,
        "spaces": [
            {
                "gmt_create": 1640524576555,
                "gmt_modified": 1677054428432,
                "sort": 1,
                "space_id": "147******928",
                "space_name": "Fit Test",
                "space_type": "PARK"
            }
        ],
        "total": 1
    },
    "success": true,
    "t": 1701079655521,
    "tid": "c977256*****e0b6121b90"
}

Failure Response Example

{
  "code": 500,
  "msg": "system error,please contact the admin",
  "success": false,
  "t": 1561378856383
}

error code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error