---
title: Basic Rules & Conventions
slug: legacy-docs/basic-rules-and-conventions
docTags: 
createdAt: 2025-03-11T07:03:30.743Z
---

:::hint{type="warning"}
This page / section pertains to **BrightSign Network** (often abbreviated **BSN**), our legacy cloud platform. Our latest cloud platform is **BSN.Cloud**. Development of BSN has largely ceased and the platform will eventually be deprecated and replaced with BSN.Cloud.
:::

# Requests Must Be Complete

All the entities and structures sent to the server in the POST/PUT request body must be structurally complete. This means that they need to contain all documented properties regardless of whether their values are needed. Unknown and optional values may be specified as either "null" or "0" but needs to be specified explicitly to remove the need for the server to guess and fill them on its own. In response, the server also will always send complete structures so the client doesn't have to check the presence of each property before reading it.

# HTTP Status Codes

The BSN REST API version 2017/01 may respond with the following HTTP status codes according to [rfc7231](https://datatracker.ietf.org/doc/html/rfc7231): 100, 200, 201, 202, 204, 300, 304, 307, 308, 400, 401, 403, 404, 405, 406, 408, 411, 412, 413, 414, 415, 429, 431, 500, 502, 503, 504, or 505. 

# Request Values

The actual values in requests must strictly match the data types in the properties. Which data types are nullable and which are not should be clearly defined. See [Custom Data Types (2020/10)](docId\:JzLv0IApLvF0-d_HXAT0h).

# Data Request Structures

Each BSN REST API data request must contain the "Accept" HTTP header. Make sure that it lists only content representations that are really supported by the client. Values like "\*" and "application\*" are accepted but produce random result from the list of representations supported by the server, which also may change from time to time, according to [rfc7231#section-3.4](https://datatracker.ietf.org/doc/html/rfc7231#section-3.4). 

Each BSN REST API data request may also contain an "Accept-Encoding" HTTP header with the list of traffic compression algorithms supported by the client (for example, "gzip" or "deflate"), and expect either non-compressed or compressed by the algorithm specified in "Content-Encoding" HTTP response header according to [rfc7231](https://datatracker.ietf.org/doc/html/rfc7231). All update/create requests should contain the "Content-Type" header. 

All endpoints support the "application/json" and "application/xml" types, except for the `/Sessions/` endpoint, which uses a unique set of content types for file uploads.

# Conditional Requests

BrightSign BSN REST APIs support conditional requests in all singular entity retrieval editing and removal methods (for example, PUT, DELETE, PATCH). You should use conditional requests when multiple retrievals of the same entity is expected and especially in update and delete requests of a single entity. They are implemented according to [rfc2616](https://datatracker.ietf.org/doc/html/rfc2616) on the server side and based on the "Last-Modified", "If-Modified-Since" and "If-Unmodified-Since" HTTP headers.

# Traffic Compression

Traffic compression for BSN REST API requests may also be implemented on demand but such case is not described in [rfcStandards](https://www.rfc-editor.org/standards) so may be based only on our agreements.