github.com/rpdict/ponzu@v0.10.1-0.20190226054626-477f29d6bf5e/docs/src/HTTP-APIs/Content.md (about)

     1  title: Content HTTP API
     2  
     3  
     4  Ponzu provides a read & write HTTP API to access and interact with content on a
     5  system. By default, write access (including create, update and delete) and search 
     6  are disabled. See the section on Ponzu's [API Interfaces](/Interfaces/API) to learn
     7  more about how to enable these endpoints.
     8  
     9  ---
    10  
    11  ## Endpoints
    12  
    13  ### Get Content by Type
    14  <kbd>GET</kbd> `/api/content?type=<Type>&id=<ID>`
    15  
    16  ##### Sample Response
    17  ```javascript
    18  {
    19    "data": [
    20      {
    21          "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
    22          "id": 6,
    23          "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18" // customizable
    24          "timestamp": 1493926453826, // milliseconds since Unix epoch
    25          "updated": 1493926453826,
    26          // your content data...,
    27      }
    28    ]
    29  }
    30  ```
    31  
    32  ---
    33  
    34  ### Get Contents by Type
    35  <kbd>GET</kbd> `/api/contents?type=<Type>`
    36  
    37    - optional params:
    38      1. `order` (string: ASC / DESC, default: DESC)
    39      2. `count` (int: -1 - N, default: 10, -1 returns all)
    40      3. `offset` (int: 0 - N, default: 0)
    41  ##### Sample Response
    42  ```javascript
    43  {
    44    "data": [
    45      {
    46          "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
    47          "id": 6,
    48          "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18", // customizable
    49          "timestamp": 1493926453826, // milliseconds since Unix epoch
    50          "updated": 1493926453826,
    51          // your content data...,
    52      },
    53      {
    54          "uuid": "5a9177c7-634d-4fb1-88a6-ef6c45de797c",
    55          "id": 7,
    56          "slug": "item-id-5a9177c7-634d-4fb1-88a6-ef6c45de797c", // customizable
    57          "timestamp": 1493926453826, // milliseconds since Unix epoch
    58          "updated": 1493926453826,
    59          // your content data...,
    60      },
    61      // more objects...
    62    ]
    63  }
    64  ```
    65  
    66  ---
    67  
    68  ### Get Content by Slug
    69  <kbd>GET</kbd> `/api/content?slug=<Slug>`
    70  
    71  ##### Sample Response
    72  ```javascript
    73  {
    74    "data": [
    75      {
    76          "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
    77          "id": 6,
    78          "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18", // customizable
    79          "timestamp": 1493926453826, // milliseconds since Unix epoch
    80          "updated": 1493926453826,
    81          // your content data...,
    82      }
    83    ]
    84  }
    85  ```
    86  
    87  ---
    88  
    89  ### New Content
    90  <kbd>POST</kbd> `/api/content/create?type=<Type>`
    91  
    92    - Type must implement [`api.Createable`](/Interfaces/API#apicreateable) interface
    93  !!! note "Request Data Encoding" 
    94      Request must be `multipart/form-data` encoded. If not, a `400 Bad Request` 
    95      Response will be returned.
    96  
    97  ##### Sample Response
    98  ```javascript
    99  {
   100    "data": [
   101      {
   102          "id": 6, // will be omitted if status is pending
   103          "type": "Review",
   104          "status": "public"
   105      }
   106    ]
   107  }
   108  ```
   109  
   110  ---
   111  
   112  ### Update Content
   113  <kbd>POST</kbd> `/api/content/update?type=<Type>&id=<id>`
   114  
   115    - Type must implement [`api.Updateable`](/Interfaces/API#apiupdateable) interface
   116  !!! note "Request Data Encoding" 
   117      Request must be `multipart/form-data` encoded. If not, a `400 Bad Request` 
   118      Response will be returned.
   119    
   120  ##### Sample Response
   121  ```javascript
   122  {
   123    "data": [
   124      {
   125          "id": 6,
   126          "type": "Review",
   127          "status": "public"
   128      }
   129    ]
   130  }
   131  ```
   132  
   133  ---
   134  
   135  ### Delete Content
   136  <kbd>POST</kbd> `/api/content/delete?type=<Type>&id=<id>`
   137  
   138    - Type must implement [`api.Deleteable`](/Interfaces/API#apideleteable) interface
   139  !!! note "Request Data Encoding" 
   140      Request must be `multipart/form-data` encoded. If not, a `400 Bad Request` 
   141      Response will be returned.
   142  
   143  ##### Sample Response
   144  ```javascript
   145  {
   146    "data": [
   147      {
   148          "id": 6,
   149          "type": "Review",
   150          "status": "deleted"
   151      }
   152    ]
   153  }
   154  ```
   155  
   156  ---
   157  
   158  ### Additional Information
   159  
   160  All API endpoints are CORS-enabled (can be disabled in configuration at run-time) and API requests are recorded by your system to generate graphs of total requests and unique client requests within the Admin dashboard.
   161  
   162  #### Response Headers
   163  The following headers are common across all Ponzu API responses. Some of them can be modified
   164  in the [system configuration](/System-Configuration/Settings) while your system is running.
   165  
   166  ##### HTTP/1.1
   167  ```
   168  HTTP/1.1 200 OK
   169  Access-Control-Allow-Headers: Accept, Authorization, Content-Type
   170  Access-Control-Allow-Origin: *
   171  Cache-Control: max-age=2592000, public
   172  Content-Encoding: gzip
   173  Content-Type: application/json
   174  Etag: MTQ5Mzk0NTYzNQ==
   175  Vary: Accept-Encoding
   176  Date: Fri, 05 May 2017 01:15:49 GMT
   177  Content-Length: 199
   178  ```
   179  
   180  ##### HTTP/2
   181  ```
   182  access-control-allow-headers: Accept, Authorization, Content-Type
   183  access-control-allow-origin: *
   184  cache-control: max-age=2592000, public
   185  content-encoding: gzip
   186  content-length: 199
   187  content-type: application/json
   188  date: Fri, 05 May 2017 01:38:11 GMT
   189  etag: MTQ5Mzk0ODI4MA==
   190  status: 200
   191  vary: Accept-Encoding
   192  ```
   193  
   194  #### Helpful links
   195  [Typewriter](https://github.com/natdm/typewriter)
   196  Generate & sync front-end data structures from Ponzu content types. ([Ponzu example](https://github.com/natdm/typewriter/blob/master/EXAMPLES.md#example-use-in-a-package-like-ponzu))