README ¶
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.
Documentation ¶
There is no documentation for this package.