api.apib

FORMAT: 1A
HOST: https://api.thegrid.io

# The Grid API

# Group User information

## User details [/user]

### Retrieving user information [GET]

+ Response 200 (application/json)

  + Body

      ```
      <!-- include(examples/user-with-avatar.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/user.json) -->
      ```

# Group Long-running jobs

Several actions in the API takes a significant time.
Current examples include POST /share, /publish and /unpublish.
Performing such an action returns a Location header with a Job URL.

## Job details [/job/{id}]

### Retriving job details [GET]

+ Parameters
  + id (required, string) - Job UUID

+ Response 200 (application/json)

  + Body

      ```
      <!-- include(examples/job-share-completed.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/job.json) -->
      ```

## Jobs [/job]

### Listing current jobs [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/job-share-completed.json) -->
      ]
      ```

# Group Newsfeed

## User's newsfeed [/updates{?offset,limit,measurements}]

### Fetch user's latest newsfeed [GET]

+ Parameters
  + offset (number) - Offset to use for pagination
  + limit (number) - Limit to use for pagination
  + measurements (string) - Selectively get only certain measurements

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/item-valid-listing-item.json) -->
      ]
      ```

# Group Site Management

## Site information [/site]

### List user websites [GET]

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/site-with-config.json) -->
      ]
      ```

### Create a website [POST]

+ Request (application/json)

  **Note:** the repository must be in `the-domains` organization. The repository name can later be used for sharing content to the newly-created site.

  + Body

      ```
      <!-- include(examples/site-without-owner.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 201

  Site was successfully created

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 422

  Missing site information

  + Body

## User website [/site/{id}]

+ Parameters
  + id (required, string) - Site UUID

### Get website details [GET]

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

### Update website details [PUT]

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/site-without-owner-with-config.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/site.json) -->
      ```

+ Response 200

### Delete website [DELETE]

+ Response 200

## Site DNS status [/site/{id}/dns]

+ Parameters
  + id (required, string) - Site UUID

### Check website DNS status [POST]

+ Response 200 (application/json)

  + Body 

      ```
      { "valid": true }
      ```

## Website discovery [/site/discover{?url}]

### Match URL to a website [GET]

+ Parameters
  + url (required, string) - URL of the website

+ Response 302

  + Headers

            Location: /site/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 409

  Grid site belonging to another user was found at the URL

  + Body

+ Response 404

  No Grid site was found for the URL

  + Body

## Redesigns [/site/{id}/redesign{?inflight}]

### Listing redesigns [GET]

Users can request a listing of the current redesigns for a website.

Whenever the site configuration is changed or new content is published, the redesigns list resets to only contain the current live design.

+ Parameters
  + id (required, string) - Site UUID
  + inflight (optional, boolean) - Whether to include in-flight redesigns in the listing

+ Response 200 (application/json)

### Requesting a redesign [POST]

New redesigns can be requested by submitting a rating on an existing design.

+ Parameters
  + id (required, string) - Site UUID

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/redesignrequest-minimal.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/redesignrequest.json) -->
      ```

+ Response 202

  + Headers

            Location: /job/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

## Redesign [/site/{id}/redesign/{redesign}{?inflight}]

### Individual redesign [GET]

+ Parameters
  + id (required, string) - Site UUID
  + redesign (required, string) - Redesign UUID
  + inflight (optional, boolean) - Whether to include in-flight redesigns in the listing

+ Response 200 (application/json)

### Publish a redesign [POST]

A site can be updated to use any of the redesigns by publishing it. This will trigger a re-solve of the website.

+ Parameters
  + id (required, string) - Site UUID
  + redesign (required, string) - Redesign UUID

+ Response 202

  + Headers

            Location: /job/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

### Delete a redesign [DELETE]

+ Parameters
  + id (required, string) - Site UUID
  + redesign (required, string) - Redesign UUID

+ Response 200

## Redesign Previews [/site/{id}/redesign/{redesign}/preview]

### Showing redesign preview [GET]

+ Parameters
  + id (required, string) - Site UUID
  + redesign (required, string) - Redesign UUID

+ Response 200 (text/html)

## Collaboration [/site/{id}/collaborator]

### Listing collaborators [GET]

Site owner can list the site's collaborators.

+ Parameters
  + id (required, string) - Site UUID

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/collaborator-accepted-by-url.json) -->
      ]
      ```


### Inviting a new collaborator [POST]

Site owner can invite new collaborators to a site. Collaborators can be invited either by email or by URL of a Grid site.

+ Parameters
  + id (required, string) - Site UUID

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/collaboratorinvite-email.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/collaboratorinvite.json) -->
      ```

+ Response 201

  Collaborator was successfully invited.

  + Body

# Group Content Management

## Share [/share]

### Sharing content [POST]

Users can share content to The Grid. The shared items will be normalized, analyzed and made available via the item API.
Sharing creates a Job, whos progress can be monitored using the /job API.

There are typically two different things you can be sharing:

* Full article pages: share with URL
* HTML fragments: selection or img tag. Share with content, type text/html and with the URL of the originating page

Note that publishing an item to a website is a separate step. See /publish

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/share-url-only.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/share.json) -->
      ```

+ Response 202

  Sharing was successful and will be processed.

  + Headers

            Location: /job/b8838e11-1d97-4799-85d8-1aafec52e927

+ Response 422

  Missing required parameters

  + Body

+ Response 403

  Not allowed to share to the specified website

  + Body

## Upload signing [/share/sign{?objectName,contentType}]

### Signing intent to upload [GET]

In situations where users want to share content from their local filesystem (images, Markdown files, etc), this is done by uploading them to Amazon S3. The share intent signing API provides a temporary upload URL, as well as the permanent URL where the file will reside after upload has completed.

After the file has been uploaded to S3, it can be shared to a Grid site using the normal [share flow](#content-management-share-post).

+ Parameters
  + objectName (string) - Name of the file being uploaded
  + contentType (string) - File MIME type

+ Response 422

  Missing required parameters

  + Body

+ Response 200 (application/json)

  A temporary upload signature has been generated. Use the provided `signedUrl` to upload via `HTTP PUT`. The `publicUrl` is the URL that the file will have after upload has completed.

  + Body

      ```
      <!-- include(examples/sharesign-response.json) -->
      ```

## Items list [/item{?published,minimal,offset,limit,site,measurements,blocktype}]

### Retrieve user's content items [GET]

+ Parameters
  + published (boolean) - Whether to get published or unpublished items only
  + minimal (boolean) - Whether to receive items without measurements applied (deprecated, use measurements instead)
  + offset (number) - Offset to use for pagination
  + limit (number) - Limit to use for pagination
  + site (string) - Receive only items associated with given site. Example: the-domains/mywebsite
  + blocktype (string) - Only items containing at least one block of given type
  + measurements (string) - Selectively get only certain measurements

When an item is being worked on by a user it is available via the API. Queries without selective measurements must be paginated. When using pagination, the `limit` must be smaller than 50.

+ Response 200 (application/json)

  + Body

      ```
      [
      <!-- include(examples/item-valid-listing-item.json) -->
      ]
      ```

### Create an item [POST]

+ Request (application/json)

  + Schema

      ```
      <!-- include(full-schema/item.json) -->
      ```

  + Body

      ```
      <!-- include(examples/item-valid-general-item.json) -->
      ```

+ Response 201

  + Headers

            Location: /item/b8838e11-1d97-4799-85d8-1aafec52e927

+ Response 422

  Missing item information

  + Body

## Item [/item/{id}{?measurements}]

+ Parameters
  + id (required, string) - Item UUID
  + measurements (string) - Selectively get only certain measurements

### Retrieve an item [GET]

+ Response 200 (application/json)

  + Schema

      ```
      <!-- include(full-schema/item.json) -->
      ```

  + Body

      ```
      <!-- include(examples/item-valid-general-item.json) -->
      ```

+ Response 404

  Item not found

  + Body

### Update item [PUT]

+ Request (application/json)

  + Schema

      ```
      <!-- include(full-schema/item.json) -->
      ```

  + Body

      ```
      <!-- include(examples/item-valid-general-item.json) -->
      ```

+ Response 200 (application/json)

  Item was successfully updated.

  + Body

+ Response 422

  Missing item information

  + Body

### Update item metadata [PATCH]

+ Response 204

  Item was successfully updated

  + Body

+ Response 422

  Missing item information

  + Body

### Remove item [DELETE]

+ Response 200

## Publishing [/publish]

### Publish a items to a site [POST]

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/publish-with-sites.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/publish.json) -->
      ```

+ Response 202

  + Headers

            Location: /job/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

## Unpublishing [/unpublish]

### Unpublish items from a site [POST]

+ Request (application/json)

  + Body

      ```
      <!-- include(examples/publish-with-sites.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/publish.json) -->
      ```

+ Response 202

  + Headers

            Location: /job/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

## Copying [/copy/{id}]

+ Parameters
  + id (required, string) - Item UUID

### Copy an item [POST]

+ Request

  + Schema

      ```
      <!-- include(full-schema/copymove.json) -->
      ```

+ Response 200

  Item was successfully copied. New item location can be found from the location header.

  + Headers

            Location: /item/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 422

  Missing item information

  + Body

## Moving [/move/{id}]

+ Parameters
  + id (required, string) - Item UUID

### Move an item to another site [POST]

+ Request

  + Schema

      ```
      <!-- include(full-schema/copymove.json) -->
      ```

+ Response 200

  Item was successfully moved.

  + Headers

            Location: /item/61a23f6a-d438-49c3-a0b9-7cd5bb0fe177

+ Response 422

  Missing item information

  + Body

## Reordering items [/reorder/item]

### Reorder an items list [POST]

+ Request

  + Body

      ```
      <!-- include(examples/reorderitems-valid-two-items.json) -->
      ```

  + Schema

      ```
      <!-- include(full-schema/reorderitems.json) -->
      ```

+ Response 200

  Items were successfully reordered.

  + Body

      ```
      [
        "bdcc6765-114a-4184-977d-b01d3132ef69",
        "b04d3a7f-689f-4bc5-a7c6-304b39f271f3"
      ]
      ```


+ Response 422

  Missing item information

  + Body