A minimalist content management system (CMS) API that persists content as JSON to a database. It is scalable, device-agnostic, extremely performant, and does not impose any architectural constraints upon the user experience that is using it. Epic is a Go language program that is compiled into a platform-specific native binary, and usually deployed as a Docker container.
1. Create the PostgreSQL database. Requires a role with administrative privileges. Using the Epic command-line tool, enter the following command, replacing the example fields with your own:
epic install postgresql --adminUser adminUser --adminPassword adminPassword --server dbServer --database epic --epicPassword epicPassword
It will return text similar to this:
Creating Epic database.
Epic database successfully created with this name: epic
Epic user created with password: epicPassword
Epic application ID is: 5345f895-68a5-4b64-bf54-aab742019489
Using the Epic command-line tool, enter the following command, replacing the example fields with your own:
epic serve http --port 7000 --host localhost --server dbServer --database epic --epicPassword epicPassword
You are done using the Epic command-line tool. Everything hereafter is executed via RESTful HTTP requests.
HTTP POST request with JSON body to "/auth/login".
{
"username":"epic",
"password":"epicPassword",
"app-id":"5345f895-68a5-4b64-bf54-aab742019489"
}
It will respond with an HTTP Response Code, and if authentication is successful, a JSON Web Token (JWT) in the HTTP 'Authorization' header.
HTTP POST request with JSON body to "/app".
{
"name": "Middle Earth",
"code": "middleearth"
}
It will return an AppID (UUIDv4) for your new application.
{"uuid":"722adbcb-3209-4ff7-9906-41c5b1384357"}
All subsequent HTTP requests will be associated with this AppID.
HTTP POST request with JSON body to "/auth/user". The JSON 'id' field is optional. It will be generated by the API, if the client does not provide it.
{
"id":"123e4567-e89b-12d3-a456-426655440000",
"first-name":"Gandalf",
"last-name":"Stormcrow",
"email":"olórin@valinor.gov",
"username":"gandalf",
"password":"mellon",
"app-id":"123e4567-e89b-12d3-a456-426655440000"
}
Responds with an HTTP Response Code and JSON body.
HTTP POST request with JSON body to "/auth/login".
{
"username":"gandalf",
"password":"mellon",
"app-id":"123e4567-e89b-12d3-a456-426655440000"
}
It will respond with an HTTP Response Code, and if authentication is successful, a JSON Web Token (JWT) in the HTTP 'Authorization' header.
You will use this JSON Web Token (JWT) in the HTTP 'Authorization' header for every subsequent HTTP request you make to the Epic API.
Congratulations! You are done with initial setup!
Use the API commands described below to create and manage your application's content!
"One Command to delete it all, and leave nothing behind then."
epic uninstall postgresql --adminUser adminUser --adminPassword adminPassword --server dbServer --database epic
HTTP GET request to ""/content/{id}"
Requires authorization HTTP POST request with JSON body to "/content"
{
"app-id":"123e4567-e89b-12d3-a456-426655440000",
"name":"Left side-bar, bottom",
"description":"Text that appears at the bottom of the left side-bar."
}
Responds with an HTTP Response Code and JSON body that either has the new Content ID or an error message.
{
"id":"123e4567-e89b-12d3-a456-426655440000"
}
Requires authorization HTTP PUT request with JSON body to "/content/{id}"
{
"id":"123e4567-e89b-12d3-a456-426655440000",
"locale":"us-EN",
"data": {
"id":"123",
"your-data":"whatever-you-want"
}
}
- Only top-level fields are used by Epic.
- The top-level id must be a UUID V4.
- The top-level 'locale' must be a valid locale string.
- The top-level 'tags' must be valid JSON consisting of an array of strings.
- Any valid JSON can go into the top-level 'data' field. Epic stores 'data' exactly as is, and does not use it use. It is your content.
- Relationships between 'content' records are established by applying one or more 'tags'.
HTTP GET request to "/app/{app-uuid}/tag/{tag}" The app-uuid is a standard version 4 UUID.
Requires authorization. HTTP POST request to "/app/{app-uuid}/tag/{tag}". The app-uuid is a standard version 4 UUID.
Requires authorization, HTTP POST request to "/content/{content-uuid}/tag/{tag}".
Requires authorization. Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environmental variables with appropriate values. HTTP POST request with JSON body to "/asset/url".
{
"bucket":"epic-content-assets",
"key":"asset-key-for-s3"
}
Responds with an HTTP Response Code and JSON body.
{
"bucket":"epic-content-assets",
"key":"asset-key-for-s3",
"url":"https://epic-content-assets.s3.amazonaws.com/asset-key-for-s3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMTULOINQ3C24OUQ%2F20160517%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20160517T123628Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=926629e70dc3cc777943b500975d5764a4824aac8d40fc63d81cda8a9d6f733c",
"error":""
}
HTTP POST request with JSON body to "/auth/login". Responds with an HTTP Response Code, and if authentication is successful, a JSON Web Token (JWT) in the HTTP 'Authorization' header. All subsequent HTTP Requests should include that JWT in the 'Authorization' header.
{
"username":"gandalf",
"password":"mellon",
"app-id":"123e4567-e89b-12d3-a456-426655440000"
}
Requires authorization. HTTP DELETE request to "/auth/logout".
Requires authorization. HTTP POST request with JSON body to "/auth/user". The JSON 'id' field is optional. It will be generated by the API, if the client does not provide it.
{
"id":"123e4567-e89b-12d3-a456-426655440000",
"first-name":"Gandalf",
"last-name":"Stormcrow",
"email":"olórin@valinor.gov",
"username":"gandalf",
"password":"mellon",
"app-id":"123e4567-e89b-12d3-a456-426655440000"
}
Responds with an HTTP Response Code and JSON body.
Requires authorization. HTTP GET request to "/auth/user".
Requires authorization. HTTP DELETE request to "/auth/user" to delete your own user account. HTTP DELETE request to "/auth/user?id=123e4567-e89b-12d3-a456-426655440000" to delete another user's account.
Requires authorization. HTTP PUT request with JSON body to "/auth/user/password". The JSON 'password' field is required, and 'id' field is optional (allowing an admin to change another user's password).
{
"password":"mellon"
}
or optionally
{
"id":"123e4567-e89b-12d3-a456-426655440000",
"password":"mellon"
}
Responds with an HTTP Response Code, and an empty JSON body (since it's a PUT request).
Requires authorization. HTTP POST request to "/auth/token". Responds with an HTTP Response Code.
Requires authorization. HTTP GET request to "/auth/uuid". Responds with an HTTP Response Code, and a new version 4 UUID in the JSON body.
{
"uuid":"123e4567-e89b-12d3-a456-426655440000"
}
Any API call that includes "Requires authorization." in the documentation requires that the HTTP Request have a valid JSON Web Token (JWT) in the HTTP 'Authorization' header.