Skip to content

Instantly share code, notes, and snippets.

@stefanoverna

stefanoverna/doc.md

Last active February 10, 2016 21:41
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save stefanoverna/72ff105549a486fc9817 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save stefanoverna/72ff105549a486fc9817 to your computer and use it in GitHub Desktop.
Download ZIP
Dato API Documentation
Raw
doc.md

Session

A session is required to access to read-and-write API endpoints

Attributes

Name Type Description Example
id string JSON web token for the session "eyJCJhbGci.eyJhaWwuY29tIn0.32wQOMci"
links:user:linkage:id string ID of user "312"
links:user:linkage:type string JSON API type field
pattern: ^user$		 "user"
type string JSON API type field
pattern: ^session$		 "session"

Session Create

Create a new session

POST /sessions

Required Parameters

Name Type Description Example
data:attributes:email email Email "foo@bar.com"
data:attributes:password string Password "changeme"
data:type string JSON API type field
pattern: ^email_credentials$		 "email_credentials"

Curl Example

$ curl -n -X POST https://dato-api.herokuapp.com/sessions \
  -d '{
  "data": {
    "type": "email_credentials",
    "attributes": {
      "email": "foo@bar.com",
      "password": "changeme"
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 201 Created

{
  "data": {
    "type": "session",
    "id": "eyJCJhbGci.eyJhaWwuY29tIn0.32wQOMci",
    "links": {
      "user": {
        "linkage": {
          "type": "user",
          "id": "312"
        }
      }
    }
  },
  "included": [
    {
      "type": "user",
      "id": "312",
      "attributes": {
        "email": "foo@bar.com",
        "first_name": "Mark",
        "last_name": "Smith"
      }
    }
  ]
}

User

Dato user

Attributes

Name Type Description Example
attributes:email string Email "foo@bar.com"
attributes:first_name string First name "Mark"
attributes:last_name string Last name "Smith"
id string ID of user "312"
type string JSON API type field
pattern: ^user$		 "user"

Space

A space represents a specific Dato backend instance

Attributes

Name Type Description Example
attributes:deploy_status string Specifies deploy status
one of:"unstarted" or "pending" or "success" or "fail"		 "unstarted"
attributes:deployable boolean Specifies whether all the deploy informations are correctly setup or not true
attributes:global_seo nullable object Specifies default global settings null
attributes:global_seo:facebook_page_url nullable object URL of facebook page "http://facebook.com/awesomewebsite"
attributes:global_seo:fallback_seo:description string "Default meta description"
attributes:global_seo:fallback_seo:image nullable object null
attributes:global_seo:fallback_seo:image:format string Image format
one of:"png" or "jpg" or "gif"		 "png"
attributes:global_seo:fallback_seo:image:height integer Image height 500
attributes:global_seo:fallback_seo:image:path string The S3 path where the file will be stored "/7/1455102967-image.png"
attributes:global_seo:fallback_seo:image:size integer The size of the image in bytes 424112
attributes:global_seo:fallback_seo:image:width integer Image width 400
attributes:global_seo:fallback_seo:title string "Default meta title"
attributes:global_seo:site_name string Site name, used in social sharing "My awesome website"
attributes:global_seo:title_suffix nullable object Title meta tag suffix " - My awesome website"
attributes:global_seo:twitter_account nullable object Twitter account associated to website "@awesomewebsite"
attributes:last_data_change_at nullable date-time Specifies the last time when a change of data occurred null
attributes:last_deploy_at nullable date-time Specifies the last time when a deploy occurred null
attributes:locales array Space available locales ["it"]
attributes:name string Space name "My blog"
attributes:no_index boolean Whether the website needs to be indexed by search engines or not true
id string ID of space "155"
links:content_types:linkage array The list of space content types [{"type":"content_type","id":"post"}]
links:menu_items:linkage array The list of space menu items [{"type":"menu_item","id":"34"}]
type string JSON API type field
pattern: ^space$		 "space"

Space Create

Create a new session

GET /space/{session_id}

Curl Example

$ curl -n https://dato-api.herokuapp.com/space/$SESSION_ID

Response Example

HTTP/1.1 200 OK

{
  "data": {
    "type": "space",
    "id": "155",
    "attributes": {
      "name": "My blog",
      "locales": [
        "it"
      ],
      "no_index": true,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "last_deploy_at": "2015-01-01T12:00:00Z",
      "deployable": true,
      "deploy_status": "unstarted",
      "global_seo": {
        "site_name": "My awesome website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My awesome website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      }
    },
    "links": {
      "menu_items": {
        "linkage": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      },
      "content_types": {
        "linkage": [
          {
            "type": "content_type",
            "id": "post"
          }
        ]
      }
    }
  },
  "included": [
    null
  ]
}

Space Update

Updates a space settings

PUT /space

Required Parameters

Name Type Description Example
data:attributes:global_seo nullable object Specifies default global settings null
data:attributes:global_seo:facebook_page_url nullable object URL of facebook page "http://facebook.com/awesomewebsite"
data:attributes:global_seo:fallback_seo:description string "Default meta description"
data:attributes:global_seo:fallback_seo:image nullable object null
data:attributes:global_seo:fallback_seo:image:format string Image format
one of:"png" or "jpg" or "gif"		 "png"
data:attributes:global_seo:fallback_seo:image:height integer Image height 500
data:attributes:global_seo:fallback_seo:image:path string The S3 path where the file will be stored "/7/1455102967-image.png"
data:attributes:global_seo:fallback_seo:image:size integer The size of the image in bytes 424112
data:attributes:global_seo:fallback_seo:image:width integer Image width 400
data:attributes:global_seo:fallback_seo:title string "Default meta title"
data:attributes:global_seo:site_name string Site name, used in social sharing "My awesome website"
data:attributes:global_seo:title_suffix nullable object Title meta tag suffix " - My awesome website"
data:attributes:global_seo:twitter_account nullable object Twitter account associated to website "@awesomewebsite"
data:attributes:no_index boolean Whether the website needs to be indexed by search engines or not true
data:id string ID of space "155"
data:type string JSON API type field
pattern: ^space$		 "space"

Curl Example

$ curl -n -X PUT https://dato-api.herokuapp.com/space \
  -d '{
  "data": {
    "type": "space",
    "id": "155",
    "attributes": {
      "no_index": true,
      "global_seo": {
        "site_name": "My awesome website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My awesome website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 200 OK

{
  "data": {
    "type": "space",
    "id": "155",
    "attributes": {
      "name": "My blog",
      "locales": [
        "it"
      ],
      "no_index": true,
      "last_data_change_at": "2015-01-01T12:00:00Z",
      "last_deploy_at": "2015-01-01T12:00:00Z",
      "deployable": true,
      "deploy_status": "unstarted",
      "global_seo": {
        "site_name": "My awesome website",
        "fallback_seo": {
          "title": "Default meta title",
          "description": "Default meta description",
          "image": {
            "path": "/7/1455102967-image.png",
            "width": 400,
            "height": 500,
            "format": "png",
            "size": 424112
          }
        },
        "title_suffix": " - My awesome website",
        "facebook_page_url": "http://facebook.com/awesomewebsite",
        "twitter_account": "@awesomewebsite"
      }
    },
    "links": {
      "menu_items": {
        "linkage": [
          {
            "type": "menu_item",
            "id": "34"
          }
        ]
      },
      "content_types": {
        "linkage": [
          {
            "type": "content_type",
            "id": "post"
          }
        ]
      }
    }
  }
}

Menu Item

A menu item helps organize content types within the backend interface

Attributes

Name Type Description Example
attributes:label string The label of the menu item "Posts"
attributes:position integer Ordering index 1
id string ID of menu item "34"
links:children:linkage array [{"type":"menu_item","id":"34"}]
links:content_type:linkage string JSON API linkage
links:parent:linkage string JSON API linkage
type string JSON API type field
pattern: ^menu_item$		 "menu_item"

Content type

A content type is a specific kind of editable content

Attributes

Name Type Description Example
attributes:name string "Blog post"
attributes:singleton boolean true
attributes:sortable boolean true
id string ID of content type "post"
links:fields:linkage array [{"type":"field","id":"124"}]
links:singleton_record:linkage string JSON API linkage
type string JSON API type field
pattern: ^content_type$		 "content_type"

Field

A field represents a single chunk of data associated to a content type

Attributes

Name Type Description Example
attributes:api_key string Field API key "title"
attributes:field_type string Type of input "title"
attributes:hint nullable string Field hint "This field will be used as post title"
attributes:label string The label of the field "Title"
attributes:localized boolean Whether the field needs to be multilanguage or not true
attributes:position integer Ordering index 1
attributes:validators object Optional field validations {"required":{}}
id string ID of field "124"
type string JSON API type field
pattern: ^field$		 "field"

Record

A record is a single instance of a Content Type

Attributes

Name Type Description Example
attributes object The JSON data associated to the record {"title":"This is a record!"}
id string ID of record "4235"
links:content_type:linkage:id string ID of content type "post"
links:content_type:linkage:type string JSON API type field
pattern: ^content_type$		 "content_type"
type string JSON API type field
pattern: ^record$		 "record"

Record Validate

Validates a record fields

POST /records/validate

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the record {"title":"This is a record!"}
data:links:content_type:linkage:id string ID of content type "post"
data:links:content_type:linkage:type string JSON API type field
pattern: ^content_type$		 "content_type"
data:type string JSON API type field
pattern: ^record$		 "record"

Curl Example

$ curl -n -X POST https://dato-api.herokuapp.com/records/validate \
  -d '{
  "data": {
    "type": "record",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 200 OK

{
  "data": {
    "type": "record",
    "id": "4235",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  },
  "included": [
    {
      "type": "content_type",
      "id": "post",
      "attributes": {
        "name": "Blog post",
        "singleton": true,
        "sortable": true
      },
      "links": {
        "singleton_record": {
          "linkage": null
        },
        "fields": {
          "linkage": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        }
      }
    }
  ]
}

Record Create

Create a new record

POST /records

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the record {"title":"This is a record!"}
data:links:content_type:linkage:id string ID of content type "post"
data:links:content_type:linkage:type string JSON API type field
pattern: ^content_type$		 "content_type"
data:type string JSON API type field
pattern: ^record$		 "record"

Curl Example

$ curl -n -X POST https://dato-api.herokuapp.com/records \
  -d '{
  "data": {
    "type": "record",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 201 Created

{
  "data": {
    "type": "record",
    "id": "4235",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  },
  "included": [
    {
      "type": "content_type",
      "id": "post",
      "attributes": {
        "name": "Blog post",
        "singleton": true,
        "sortable": true
      },
      "links": {
        "singleton_record": {
          "linkage": null
        },
        "fields": {
          "linkage": [
            {
              "type": "field",
              "id": "124"
            }
          ]
        }
      }
    }
  ]
}

Record Update

Updates a record

PUT /space/{record_id}

Required Parameters

Name Type Description Example
data:attributes object The JSON data associated to the record {"title":"This is a record!"}
data:id string ID of record "4235"
data:type string JSON API type field
pattern: ^record$		 "record"

Curl Example

$ curl -n -X PUT https://dato-api.herokuapp.com/space/$RECORD_ID \
  -d '{
  "data": {
    "type": "record",
    "id": "4235",
    "attributes": {
      "title": "This is a record!"
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 200 OK

{
  "data": {
    "type": "record",
    "id": "4235",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  }
}

Record Index

Lists records

GET /records

Optional Parameters

Name Type Description Example
filter[query] string textual query to match "foo"
filter[type] string content type to filter "post"
page[limit] integer number of items to fetch
default: 30		 15
page[offset] integer index of first item to fetch
default: 1		 2

Curl Example

$ curl -n https://dato-api.herokuapp.com/records
 -G \
  -d filter[type]=post \
  -d filter[query]=foo \
  -d page[offset]=2 \
  -d page[limit]=15

Response Example

HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "record",
      "id": "4235",
      "attributes": {
        "title": "This is a record!"
      },
      "links": {
        "content_type": {
          "linkage": {
            "type": "content_type",
            "id": "post"
          }
        }
      }
    }
  ],
  "meta": {
    "total_count": 42
  }
}

Record Show

Show record

GET /space/{record_id}

Curl Example

$ curl -n https://dato-api.herokuapp.com/space/$RECORD_ID

Response Example

HTTP/1.1 200 OK

{
  "data": {
    "type": "record",
    "id": "4235",
    "attributes": {
      "title": "This is a record!"
    },
    "links": {
      "content_type": {
        "linkage": {
          "type": "content_type",
          "id": "post"
        }
      }
    }
  }
}

Upload request

To upload a file in Dato through a direct PUT request, first you need an upload permission.

Attributes

Name Type Description Example
attributes:url string The URL to use to PUT the file "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"
id string The S3 path where the file will be stored "/7/1455102967-image.png"
type string JSON API type field
pattern: ^upload_request$		 "upload_request"

Upload request Create

Create a new upload request

POST /upload-requests

Required Parameters

Name Type Description Example
data:attributes:filename string The original file name "image.png"
data:type string JSON API type field
pattern: ^upload_request$		 "upload_request"

Curl Example

$ curl -n -X POST https://dato-api.herokuapp.com/upload-requests \
  -d '{
  "data": {
    "type": "upload_request",
    "attributes": {
      "filename": "image.png"
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/1.1 201 Created

{
  "data": {
    "type": "upload_request",
    "id": "/7/1455102967-image.png",
    "attributes": {
      "url": "https://dato-images.s3-eu-west-1.amazonaws.com/7/1455102967-image.png?X-Amz-Credential=AKIAJDTXTZHHDUCKAUMA%2F20160210"
    }
  }
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment