Equipment

Resource description

All endpoints adhere to the JSON API specification.

Attributes

Name

Description

Required?

Type

Notes

name

Display name

True

string

Relationships

Name

Description

Required?

Type

Notes

parent

Parent Equipment for this Equipment

False

Foreign Key
A Foreign Key between one Equipment record and another Equipment record
allows us to create an Equipment hierarchy.

utility

Utility for this Equipment

True

Foreign Key

List Equipment

A user must have at least “spectator” authorization to list Equipment for their Utility.

GET https://reliability.api.publicpower.org/v1/equipment/

Example request:

GET /v1/equipment/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers
Query Parameters

  • page (int) – Page Number of results to request.

  • page_size (int) – Number of results to return per-page.

  • filter[utility] (int) – Only return results for a given Utility ID.

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "first": "https://reliability.api.publicpower.org/v1/equipment/?page=1",
    "last": "https://reliability.api.publicpower.org/v1/equipment/?page=1",
    "next": "https://reliability.api.publicpower.org/v1/equipment/?page=1",
    "prev": null
  },
  "data": [
    {
      "type": "Equipment",
      "id": "41659",
      "attributes": {
        "name": "Cable 5"
      },
      "relationships": {
        "parent": {
          "data": {
            "type": "Equipment",
            "id": "11166"
          }
        },
        "utility": {
          "data": {
            "type": "Utility",
            "id": "177"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pages": 1,
      "count": 1
    }
  }
}
Status Codes

  • 200 OK – Successful response

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Create Equipment

A user must have “leader” authorization to create Equipment for a Utility.

POST https://reliability.api.publicpower.org/v1/equipment/

Example request:

POST /v1/equipment/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "type": "Equipment",
    "attributes": {
      "name": "Cable 5"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "177"
        }
      }
    }
  }
}
Request Headers

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Equipment",
    "id": "41660",
    "attributes": {
      "name": "Cable 5"
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "utility": {
        "data": {
          "type": "Utility",
          "id": "177"
        }
      }
    }
  }
}
Status Codes

Retrieve Equipment

A user must have at least “spectator” authorization to retrieve Equipment for their Utility.

GET https://reliability.api.publicpower.org/v1/equipment/(int: equipment_id)/

Example request:

GET /v1/equipment/41660/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Equipment",
    "id": "41660",
    "attributes": {
      "name": "Cable 5"
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "utility": {
        "data": {
          "type": "Utility",
          "id": "177"
        }
      }
    }
  }
}
Status Codes

  • 200 OK – Successful response

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Update Equipment

A user must have “leader” authorization to update Equipment for their Utility.

PATCH https://reliability.api.publicpower.org/v1/equipment/(int: equipment_id)/

Example request:

PATCH /v1/equipment/1070755/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken


{
  "data": {
    "type": "Equipment",
    "id": "41660",
    "attributes": {
      "name": "Cable 6"
    }
  }
}
Request Headers

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Equipment",
    "id": "41660",
    "attributes": {
      "name": "Cable 6"
    },
    "relationships": {
      "parent": {
        "data": null
      },
      "utility": {
        "data": {
          "type": "Utility",
          "id": "177"
        }
      }
    }
  }
}
Status Codes

  • 200 OK – Equipment updated

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Delete Equipment

A user must have “leader” authorization to delete Equipment for their Utility.

DELETE https://reliability.api.publicpower.org/v1/equipment/(int: equipment_detail_id)/

Example request:

DELETE /v1/equipment/41660/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers

Example response:

HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json
Status Codes