# OYOD Home API Docs

Once a oyod-app obtains an access token, it can use the token to access Home data via these APIs.


## Path-Value API

(See [oyod-app](https://github.com/oyod/oyod-app) for a client implementation in JavaScript).

The Path-Value API allows you to store data via a folder-like interface. This not only allows for efficient key-value usage, but also for retrieving a list of values in a given path.


### POST /v1/pv/p/PATH

Creates a datapoint with a generated uuid name at a specified `PATH`.

- `PATH` is a url path, e.g. `/my/own/thing`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- NOTE: generated uuid names are formatted `:[a-zA-Z0-9-]`

Example: `POST /v1/pv/d/some/thing/my-todos  {"title":"try it out"}`


### PUT /v1/pv/p/PATH/POINT

Creates or updates a datapoint named `POINT` at a specified `PATH`.

- `PATH` is a url path, e.g. `/my/own/thing`
- `POINT` is a datapoint name, e.g. `:the-datapoint`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- Returns `201` or `200`

Example: `PUT /v1/pv/d/my/paaath/:my-key  {"my":"data"}`


### PATCH /v1/pv/p/PATH/POINT

Updates a datapoint's value by merging it with the request body.

- `PATH` is a url path, e.g. `/my/own/thing`
- `POINT` is a datapoint name, e.g. `:the-datapoint`
- Datapoint must already exist


Example: `PATCH /v1/pv/d/my/paaath/:my-key  {"new":"stuff"}`


### GET /v1/pv/p/PATH

Retrieves an array of datapoints directly under `PATH`.

- `PATH` is a url path, e.g. `/my/own/thing`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- NOTE: This is not recursive
- Returns an empty array if there are no datapoints under this `PATH`

Example: `GET /v1/pv/d/my-things`


### GET /v1/pv/p/PATH/POINT

Retrieves a single datapoint if it exists.

- `PATH` is a url path, e.g. `/my/own/thing`
- `POINT` is a datapoint name, e.g. `:the-datapoint`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- Returns a 404 if datapoint does not exist.

Example: `GET /v1/pv/d/my-collection/:specificly-this`


### GET /v1/pv/d/POINT

**NOT IMPLEMENTED. Voice your opinion in a github issue!**

Retrieves a single datapoint by name.

- `POINT` is a datapoint name, e.g. `:the-datapoint`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- Returns a 404 if datapoint does not exist.
- If multiple datapoints have the same given name, one will be chosen in a non-defined manner.


### DELETE /v1/pv/p/PATH/POINT

Solf-deletes a single datapoint.

- `PATH` is a url path, e.g. `/my/own/thing`
- `POINT` is a datapoint name, e.g. `:the-datapoint`
- Valid characters are `[a-z0-9-_.]`, and must begin with `[a-z0-9]`
- Returns a 404 if datapoint does not exist.
- oyod-apps cannot hard delete data.

Example: `DELETE /v1/pv/d/my-collection/:specificly-this`