Skip to content
Permalink
Browse files

Lots of updates.

  • Loading branch information...
ericisaiah committed Aug 6, 2013
1 parent cc24c0a commit 9407ed83a494766484247b5607d386636fd145b9
@@ -0,0 +1 @@
.DS_Store
@@ -1,18 +1,18 @@
# Resource Server API Documentation

### [Requests](requests.md)
### [Requests](/docs/requests.md)

### [Responses](responses.md)
### [Responses](/docs/responses.md)

### Resources

[Clients](resources/clients.md)
[Clients](/docs/resources/clients.md)

[Providers](resources/providers.md)
[Providers](/docs/resources/providers.md)

* [Comments](resources/providers/comments.md)
* [Locations](resources/providers/locations.md)
* [Opportunities](resources/providers/opportunities.md)
* [Ratings](resources/providers/ratings.md)
* [Services](resources/providers/serivces.md)
* [Tags](resources/providers/tags.md)
* [Comments](/docs/resources/providers/comments.md)
* [Locations](/docs/resources/providers/locations.md)
* [Opportunities](/docs/resources/providers/opportunities.md)
* [Ratings](/docs/resources/providers/ratings.md)
* [Services](/docs/resources/providers/serivces.md)
* [Tags](/docs/resources/providers/tags.md)
BIN +6 KB docs/.DS_Store
Binary file not shown.
@@ -0,0 +1,49 @@
# Requests

## Request Signature

### Why we use a request signature

A request signature is a common cryptographic technique that enables the receiver of a message to confirm the identity of the sender.

### How it works

Just add a timestamp and request signature as two additional HTTP headers to all `POST`, `PUT`, and `DELETE` requests.

1. The timestamp header is labeled `1deg-Date` and is an ISO 8601-formatted timestamp.
2. The request signature header is labeled `1deg-Signature`. See below for instructions on how to construct it.

### How to construct the request signature

This should be a hexadecimal digest of lowercase letters and numbers. It should be constructed as follows:

1. Create the string to sign:

a. Take the parameters being submitted with the request, and sort the parameters alphabetically in descending order. These parameters should include any resource ID parameters specified in the endpoint. For example, the parameters collection for the endpoint `/v1/resources/:resource_id/locations/:id` should include `resource_id` and `id`.
b. URL encode the parameter names and values. Use `%20` for space (' ') instead of `+`.
c. Connect each parameter in a `key=value` format and append them to each other, joined by ampersands (`&`). For example, `name=Organization%20Inc&description=An%20example`.

2. Create an HMAC digest of the string created in step 1, using your API secret token as the key.

3. Create an HMAC digest of the ISO 8601-formatted timestamp submitted in the `1deg-Date` header, using the string created in step 2 as the key.

4. Create a SHA2 hexadecimal digest of the string created in step 3.

### Example Code

#### Ruby

params = {
resource_id: 3841,
name: "Existing Resource Provider, Inc."
website: "http://www.this.isan/example"
}
param_string = ""
params.keys.sort.each do |key|
param_string << "&" unless str.blank?
param_string << "#{ERB::Util.url_encode(key.to_s)}=#{ERB::Util.url_encode(params[key].to_s)}"
end
date = "2013-08-02T00:06:54Z"
signed_params = OpenSSL::HMAC.digest('sha256', my_secret_token, param_string)
signed_date = OpenSSL::HMAC.digest('sha256', signed_params, date)
signature = Digest::SHA2.hexdigest(signed_date)
@@ -0,0 +1,45 @@
# Requests

## Base URL

All calls are made to the base URL, along with the specific provider path:

https://xxxxx.xxxx.org/v1/

## Required Parameter

All requests require an API key parameter `api_key`.

## Request Signatures

All requests with the `POST`, `PUT`, or `DELETE` HTTP verbs must include two additional headers in the request: `1deg-Date` and `1deg-Signature`.

### `1deg-Date`

This is a timestamp in ISO 8601 format at UTC. Requests that are received more or fewer than 60 seconds from the time specified in this header will be rejected.

Example header:

1deg-Date: 2013-08-02T00:06:54Z

### `1deg-Signature`

This is the request signature that authenticates the sender. [Learn about how to build this request signature here.](request-signatures.md)

## Standard Parameters

Similar request types use the same standard parameters. E.g. Requests to list providers use the same filter paramters.

### Timestamps

All timestamps should be in ISO 8601 format:

YYYY-MM-DDTHH:mm:ss

### Pagination parameters

Parameter | Type | Description
--------------|-----------|--------------------------------
`page` | `integer` | The offset.
`per_page` | `integer` | The number of items to return.
`order` | `string` | The sort order by which items will be returned. Common values are `name_asc` and `name_desc`. Defaults to `name_asc`.
Binary file not shown.
@@ -0,0 +1,37 @@
# Resources

## Clients

### Attributes

Field | Type | Optional | Description
-------------|-------------|----------|-------------------------
`id` | `integer` | | The unique API client ID.
`name` | `string` | | The name of the API client.
`is_admin` | `boolean` | | Whether or not the API client is an admin.

### Endpoints

#### `GET clients`

Returns a list of API clients. Standard pagination parameters apply.

#### `POST clients`

Creates a new API client.

#### `GET clients/:id`

Returns a specific API client.

#### `PUT clients/:id`

Updates a specific API client.

#### `DELETE clients/:id`

Deletes a specific API client.

### Permissions

* Only admins can manage clients.
@@ -0,0 +1,45 @@
# Resources

## Resource Providers ("Resources")

### Attributes

Field | Type | Optional | Description
---------------|--------------|----------|---------------------------------------
`id` | `integer` | | Unique resource ID.
`name` | `string` | | The name of the resource provider.
`website` | `string` | yes | The URL of the resource provider's website.
`description` | `text` | yes | The description of the resource provider.
`picture_path` | `string` | yes | URL of the resource's profile photo or logo.
`updated_at` | `string` | yes | URL of the resource's profile photo or logo.

### Endpoints

#### `GET /v1/resources`

Returns a list of resource. Standard pagination parameters apply.

#### `POST /v1/resources`

Creates a new resource.

#### `GET /v1/resources/:id`

Returns a specific resource, along with the following nested objects:

- [`properties`](/docs/providers/properties.md)
- [`tags`](/docs/providers/tags.md)

#### `PUT /v1/resources/:id`

Updates a resource.

#### `DELETE /v1/resources/:id`

Deletes a resource.

### Permissions

* Anyone can add a new resource.
* Only admins and the original resource owner can update a resource.
* Only admins can delete a resource.
@@ -0,0 +1,35 @@
# Resources

## Comments on Providers

### Attributes

Field | Type | Optional | Description
-----------------|-----------|----------|------------------------------------
`content` | `text` | | The content text of the body. This should be plain text and should not contain any HTML or other markup.
`client_user_id` | `string` | | The ID of the user who made this comment. This should be a unique identifier in the client's application.
`response_to_id` | `integer` | yes | If this comment is in response to another comment, this should be the ID of that original comment.


### Endpoints

#### `GET providers/:resource_id/comments`

Returns the list of comments on a provider.

#### `POST providers/:resource_id/comments`

Creates a new comment on a resource.

#### `PUT providers/:resource_id/comments/:id`

Updates a comment.

#### `DELETE providers/:resource_id/comments/:id`

Deletes a comment.

### Permissions

* Anyone can add a comment on a resource.
* Only admins and the API client that submitted the original comment can update or delete it.
@@ -0,0 +1,111 @@
# Resources

## Locations on Resource Providers

### Attributes

Field | Type | Optional | Description
---------------|--------------|-----------|------------------------------------
`id` | `integer` | | Unique resource ID.
`name` | `string` | | The name of the location.
`is_primary` | `boolean` | | Whether or not this is the resource's primary location.
`address` | `string` | yes | The location's street address website.
`unit` | `string` | yes | The address unit, such as suite or level number.
`city` | `string` | | The location's city.
`state` | `string` | | The location's 2-letter state abbreviation.
`zip_code` | `string` | yes | The location's USPS Zip code.
`lat` | `float` | read-only | The latitude of the location.
`long` | `float` | read-only | The longitude of the location.

### Endpoints

#### `GET resources/:resource_id/locations`

Returns a location.

#### `POST resources/:resource_id/locations`

#### `GET resources/:resource_id/locations/:id`

Returns a specific location with the following nested resources:

- `phones`
- `schedule`

#### `PUT resources/:resource_id/locations/:id`

#### `DELETE resources/:resource_id/locations/:id`

#### Permissions

* Only resource owners and admins can manage locations, schedules, and phone numbers.

## Phones on Locations

### Attributes

Field | Type | Optional | Description
----------------|--------------|----------|------------------------------------
`id` | `integer` | | The unique ID of the phone number.
`digits` | `string` | | The phone number.
`phone_type` | `string` | yes | The type of phone number such as `fax` or `main`.
`is_primary` | `boolean` | | Whether or not this is the location's primary phone number.


### Endpoints

#### `GET resources/:resource_id/locations/:id/phones`

Returns all phone numbers on a location.

#### `POST resources/:resource_id/locations/:location_id/phones`

Creates a phone number on a location.

#### `PUT resources/:resource_id/locations/:location_id/phones/:id`

Updates a location's phone number.

#### `DELETE resources/:resource_id/locations/:location_id/phones/:id`

Deletes a location's phone number.

## Schedules on Locations

### Attributes

Field | Type | Optional | Description
------------------|--------------|----------|---------------------------------
`monday_start` | `string` | yes | The Monday opening hour of the location.
`monday_end` | `string` | yes | The Monday closing hour of the location.
`tuesday_start` | `string` | yes | The Monday opening hour of the location.
`tuesday_end` | `string` | yes | The Monday closing hour of the location.
`wednesday_start` | `string` | yes | The Monday opening hour of the location.
`wednesday_end` | `string` | yes | The Monday closing hour of the location.
`thursday_start` | `string` | yes | The Monday opening hour of the location.
`thursday_end` | `string` | yes | The Monday closing hour of the location.
`friday_start` | `string` | yes | The Monday opening hour of the location.
`friday_end` | `string` | yes | The Monday closing hour of the location.
`saturday_start` | `string` | yes | The Monday opening hour of the location.
`saturday_end` | `string` | yes | The Monday closing hour of the location.
`sunday_start` | `string` | yes | The Monday opening hour of the location.
`sunday_end` | `string` | yes | The Monday closing hour of the location.
`notes` | `text` | yes | The Monday opening hour of the location.

All hours `string` fields are of the format:

HH:mm

### Endpoints

#### `POST resources/:resource_id/locations/:id/schedule`

Creates a schedule on a location. Only one schedule can exist for a location.

#### `PUT resources/:resource_id/locations/:id/schedule`

Updates a location's schedule.

#### `DELETE resources/:resource_id/locations/:id/schedule`

Deletes the location's schedule.
@@ -0,0 +1,35 @@
# Resources

## Opportunities on Service Providers

An opportunity represents an event, appointment, resource, or other offering that the provider makes available. Opportunities are specific, that is to say, they represent a discrete item that can be added to an end user's list of tasks.

An exmple might be a job training class, which meets at a specific time and place. An implementation of a task list might allow the user to add this training class to her schedule.

### Attributes

Field | Type | Optional | Description
-----------------|--------------|-----------|--------------------------------
`id` | `integer` | | Unique opportunity ID.
`title` | `string` | | The name of the opportunity.
`is_appointment` | `boolean` | | Whether or not this is an appointment.
`description` | `text` | yes | The opportunity's description.
`requirements` | `text` | yes | The opportunity's requirements.

### Endpoints

#### `GET resources/:resource_id/opportunities`

Returns the list of opportunities on a provider.

#### `POST resources/:resource_id/opportunities`

Creates a new opportunity on a provider.

#### `PUT resources/:resource_id/opportunities/:id`

Updates an opportunity.

#### `DELETE resources/:resource_id/opportunities/:id`

Deletes an opportunity.

0 comments on commit 9407ed8

Please sign in to comment.
You can’t perform that action at this time.