epic

Epic Content Microservice

Getting Started

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

2. Start the Epic API web server using your new Epic credentials.

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.

3. Authenticate using your new Epic credentials and the Epic application ID received in #1.

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.

4. Create an application of your own.

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.

5. Create your own user for your new application.

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.

6. Authenticate using your new credentials and your new AppID.

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!

Uninstall Epic

"One Command to delete it all, and leave nothing behind then."

epic uninstall postgresql --adminUser adminUser --adminPassword adminPassword --server dbServer --database epic

Content Management

Read Content

HTTP GET request to ""/content/{id}"

Create Content

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"
}

Update Content

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'.

Read All Content Associated With A Specific Tag

HTTP GET request to "/app/{app-uuid}/tag/{tag}" The app-uuid is a standard version 4 UUID.

Create Tag

Requires authorization. HTTP POST request to "/app/{app-uuid}/tag/{tag}". The app-uuid is a standard version 4 UUID.

Assign Tag To Content

Requires authorization, HTTP POST request to "/content/{content-uuid}/tag/{tag}".

Create Presigned URL For AWS S3 PUT Operation

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":""
}

User Management

Login

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"
}

Logout

Requires authorization. HTTP DELETE request to "/auth/logout".

Create User

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.

Get User / Users

Requires authorization. HTTP GET request to "/auth/user".

Delete 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.

Update Password

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).

Authenticate Token

Requires authorization. HTTP POST request to "/auth/token". Responds with an HTTP Response Code.

New UUID

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.