Edara API v3: Districts

Read the guide first: authentication, paging, errors, rate limits and the shared PagedResult, BatchResult and *Reference shapes.

• GET /v3/districts: Lists districts.
• GET /v3/districts/{id}: Gets a district by id.
• POST /v3/districts: Creates a district.
• PUT /v3/districts/{id}: Updates a district.
• DELETE /v3/districts/{id}: Deletes a district.

Endpoints

GET /v3/districts: Lists districts.

Operation GetDistricts · permission read:district

Query string: GetDistrictsQuery

Responses: OK PagedResult<DistrictResponse>: Paged list of districts.

Notes

• name is a partial match: it finds every district whose name contains the text you send. A name that is only whitespace is ignored.
• cityId is an exact match. There are no other filters.
• Results are ordered by name, then by id.
• totalCount is the number of districts that match the filters, not the number on the page.
• When nothing matches you get 200 with an empty items list and totalCount 0.
• Tab characters are removed from name in this list. The get-by-id endpoint returns name as stored, so the two can differ.

GET /v3/districts/{id}: Gets a district by id.

Operation GetDistrictById · permission read:district

Parameters

Responses: OK DistrictResponse: The district.

Notes

• An id that does not exist returns 404.
• name is returned exactly as stored. The list endpoint removes tab characters from name, so the two can differ.

POST /v3/districts: Creates a district.

Operation CreateDistrict · permission create:district

Body: DistrictUpsertRequest

Responses: Created DistrictResponse: The created district.

Business errors (HTTP 409, match on errorCode):

• DupplicatedName: Another district already uses the same name in the same city.

Notes

• Only name and cityId are read from the body. name is trimmed before it is saved.
• A cityId that does not exist returns 400 with no errorCode.
• A district name must be unique within its city. A duplicate returns 409 with errorCode DupplicatedName, and the same name under a different city is allowed.

PUT /v3/districts/{id}: Updates a district.

Operation UpdateDistrict · permission update:district

Parameters

Body: DistrictUpsertRequest

Responses: OK DistrictResponse: The updated district.

Business errors (HTTP 409, match on errorCode):

• DupplicatedName: Another district already uses the same name in the same city.

Notes

• This is a full replace, not a partial update. Send both name and cityId every time; leaving out cityId returns 400.
• An id that does not exist returns 404 before anything is changed.
• A name already used by another district in the same city returns 409 with errorCode DupplicatedName.
• A cityId that does not exist returns 400 with no errorCode.

DELETE /v3/districts/{id}: Deletes a district.

Operation DeleteDistrict · permission delete:district

Parameters

Responses: NoContent: (not declared; read from the method body)

Business errors (HTTP 409, match on errorCode):

• ItemCannotDeleteItInUse: The district is still referenced by related records and cannot be deleted.

Notes

• The delete is permanent.
• An id that does not exist returns 404. Success returns 204.
• A district that is still in use returns 409 with errorCode ItemCannotDeleteItInUse. A district is in use when a street, customer, customer address, warehouse or account refers to it.

Types

DistrictResponse

Response describing a district.