summaryrefslogtreecommitdiff
path: root/docs/src/HTTP-APIs
diff options
context:
space:
mode:
Diffstat (limited to 'docs/src/HTTP-APIs')
-rw-r--r--docs/src/HTTP-APIs/Content.md196
-rw-r--r--docs/src/HTTP-APIs/File-Metadata.md29
-rw-r--r--docs/src/HTTP-APIs/Search.md47
3 files changed, 272 insertions, 0 deletions
diff --git a/docs/src/HTTP-APIs/Content.md b/docs/src/HTTP-APIs/Content.md
new file mode 100644
index 0000000..6a3e387
--- /dev/null
+++ b/docs/src/HTTP-APIs/Content.md
@@ -0,0 +1,196 @@
+title: Content HTTP API
+
+
+Ponzu provides a read & write HTTP API to access and interact with content on a
+system. By default, write access (including create, update and delete) and search
+are disabled. See the section on Ponzu's [API Interfaces](/Interfaces/API) to learn
+more about how to enable these endpoints.
+
+---
+
+## Endpoints
+
+### Get Content by Type
+<kbd>GET</kbd> `/api/content?type=<Type>&id=<ID>`
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
+ "id": 6,
+ "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18" // customizable
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ // your content data...,
+ }
+ ]
+}
+```
+
+---
+
+### Get Contents by Type
+<kbd>GET</kbd> `/api/contents?type=<Type>`
+
+ - optional params:
+ 1. `order` (string: ASC / DESC, default: DESC)
+ 2. `count` (int: -1 - N, default: 10, -1 returns all)
+ 3. `offset` (int: 0 - N, default: 0)
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
+ "id": 6,
+ "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18", // customizable
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ // your content data...,
+ },
+ {
+ "uuid": "5a9177c7-634d-4fb1-88a6-ef6c45de797c",
+ "id": 7,
+ "slug": "item-id-5a9177c7-634d-4fb1-88a6-ef6c45de797c", // customizable
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ // your content data...,
+ },
+ // more objects...
+ ]
+}
+```
+
+---
+
+### Get Content by Slug
+<kbd>GET</kbd> `/api/content?slug=<Slug>`
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
+ "id": 6,
+ "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18", // customizable
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ // your content data...,
+ }
+ ]
+}
+```
+
+---
+
+### New Content
+<kbd>POST</kbd> `/api/content/create?type=<Type>`
+
+ - Type must implement [`api.Createable`](/Interfaces/API#apicreateable) interface
+!!! note "Request Data Encoding"
+ Request must be `multipart/form-data` encoded. If not, a `400 Bad Request`
+ Response will be returned.
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "id": 6, // will be omitted if status is pending
+ "type": "Review",
+ "status": "public"
+ }
+ ]
+}
+```
+
+---
+
+### Update Content
+<kbd>POST</kbd> `/api/content/update?type=<Type>&id=<id>`
+
+ - Type must implement [`api.Updateable`](/Interfaces/API#apiupdateable) interface
+!!! note "Request Data Encoding"
+ Request must be `multipart/form-data` encoded. If not, a `400 Bad Request`
+ Response will be returned.
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "id": 6,
+ "type": "Review",
+ "status": "public"
+ }
+ ]
+}
+```
+
+---
+
+### Delete Content
+<kbd>POST</kbd> `/api/content/delete?type=<Type>&id=<id>`
+
+ - Type must implement [`api.Deleteable`](/Interfaces/API#apideleteable) interface
+!!! note "Request Data Encoding"
+ Request must be `multipart/form-data` encoded. If not, a `400 Bad Request`
+ Response will be returned.
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "id": 6,
+ "type": "Review",
+ "status": "deleted"
+ }
+ ]
+}
+```
+
+---
+
+### Additional Information
+
+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.
+
+#### Response Headers
+The following headers are common across all Ponzu API responses. Some of them can be modified
+in the [system configuration](/System-Configuration/Settings) while your system is running.
+
+##### HTTP/1.1
+```
+HTTP/1.1 200 OK
+Access-Control-Allow-Headers: Accept, Authorization, Content-Type
+Access-Control-Allow-Origin: *
+Cache-Control: max-age=2592000, public
+Content-Encoding: gzip
+Content-Type: application/json
+Etag: MTQ5Mzk0NTYzNQ==
+Vary: Accept-Encoding
+Date: Fri, 05 May 2017 01:15:49 GMT
+Content-Length: 199
+```
+
+##### HTTP/2
+```
+access-control-allow-headers: Accept, Authorization, Content-Type
+access-control-allow-origin: *
+cache-control: max-age=2592000, public
+content-encoding: gzip
+content-length: 199
+content-type: application/json
+date: Fri, 05 May 2017 01:38:11 GMT
+etag: MTQ5Mzk0ODI4MA==
+status: 200
+vary: Accept-Encoding
+```
+
+#### Helpful links
+[Typewriter](https://github.com/natdm/typewriter)
+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))
diff --git a/docs/src/HTTP-APIs/File-Metadata.md b/docs/src/HTTP-APIs/File-Metadata.md
new file mode 100644
index 0000000..19d6ab6
--- /dev/null
+++ b/docs/src/HTTP-APIs/File-Metadata.md
@@ -0,0 +1,29 @@
+title: File Metadata HTTP API
+
+Ponzu provides a read-only HTTP API to get metadata about the files that have been uploaded to your system. As a security and bandwidth abuse precaution, the API is only queryable by "slug" which is the normalized filename of the uploaded file.
+
+---
+
+### Endpoints
+
+#### Get File by Slug (single item)
+<kbd>GET</kbd> `/api/uploads?slug=<Slug>`
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
+ "id": 6,
+ "slug": "filename.jpg",
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ "name": "filename.jpg",
+ "path": "/api/uploads/2017/05/filename.jpg",
+ "content_length": 357557,
+ "content_type": "image/jpeg",
+ }
+ ]
+}
+``` \ No newline at end of file
diff --git a/docs/src/HTTP-APIs/Search.md b/docs/src/HTTP-APIs/Search.md
new file mode 100644
index 0000000..2939cce
--- /dev/null
+++ b/docs/src/HTTP-APIs/Search.md
@@ -0,0 +1,47 @@
+title: Full-text Search HTTP API
+
+Ponzu provides a read-only HTTP API to search the contents of your system's database.
+Full-text search is made possible by the use of [Bleve](http://blevesearch.com),
+which handles the indexing and querying.
+
+---
+
+### Endpoints
+
+#### Search Content
+
+<kbd>GET</kbd> `/api/search?type=<Type>&q=<Query String>`
+
+!!! warning "Search must be enabled individually for each Content type"
+ - Search is not on by default to protect your data in case it shouldn't be indexed and published via the API.
+ - `SearchMapping()` is implemented with default mapping (ideal for 99% of use cases).
+ - To enable search, add a `IndexContent() bool` method to your content type and return `true` (default implementation returns false).
+
+- `<Type>` must implement [db.Searchable](/Interfaces/Search/#searchsearchable)
+
+- Search is currently limited to single `<Type>` per request
+
+- `<Query String>` documentation here: [Bleve Docs - Query String](http://www.blevesearch.com/docs/Query-String-Query/)
+
+- Search results are formatted exactly the same as standard Content API calls, so you don't need to change your client data model
+
+- Search handler will respect other interface implementations on your content, including:
+ - [`item.Hideable`](https://godoc.org/github.com/ponzu-cms/ponzu/system/item#Hideable)
+ - [`item.Omittable`](https://godoc.org/github.com/ponzu-cms/ponzu/system/item#Omittable)
+ - [`item.Pushable`](https://godoc.org/github.com/ponzu-cms/ponzu/system/item#Pushable) _(Note: only the first search result will be pushed)_
+
+##### Sample Response
+```javascript
+{
+ "data": [
+ {
+ "uuid": "024a5797-e064-4ee0-abe3-415cb6d3ed18",
+ "id": 6,
+ "slug": "item-id-024a5797-e064-4ee0-abe3-415cb6d3ed18", // customizable
+ "timestamp": 1493926453826, // milliseconds since Unix epoch
+ "updated": 1493926453826,
+ // your content data...,
+ }
+ ]
+}
+```
generated by cgit v1.2.3 (git 2.25.1) at 2025-06-27 13:02:42 +0000