open-hubagent
v0.1.20
Published
A system designed to exchange Knowledge Object data with the Evidence Hub, enabling both sending and receiving of information.
Downloads
28
Readme
Open HubAgent
The Open HubAgent npm package is used for exchanging Knowledge Objects with EvidenceHub using the v2 Generic KO format.
Environment Variables
The .env file is at the root of your npm project.
Sample '.env' content
EVIDENCEHUB_API_URL=https://hub.evidentli.com/api #required
EVIDENCEHUB_API_KEY=cln12su3e000008l4gv6qb8o5 #required
HUBAGENT_PORT=3111 #optional. defaults to 3111.
HTTP_PROXY=http://localhost:6161 #optional. defaults to no proxyModify EVIDENCEHUB_API_KEY with a valid EvidenceHub Api key.
Quickstart
The following code will start a basic open-hubagent server with a custom route.
import app, { config, logger } from 'open-hubagent'
const server = app({
logger
})
// add custom route at /custom
server.register(async (api, opts, done) => {
api.get('/custom', async (request, reply) => {
const checkHealth = await api.inject({
method: 'GET',
url: '/'
})
/* e.g. perform pre/post-processing on knowledge object (ko)
const myobject = await api.inject({
method: 'GET',
url: '/api/v2/knowledge/cln17xg7h0003sk03b6twuu0p',
})
console.log(myobject)
interop with other services
*/
return { response: checkHealth.json() }
})
done()
})
const start = async () => {
try {
await server.listen({
port: config.get('server.port'),
host: '0.0.0.0'
})
const msg = `Server started listening on port ${config.get('server.port')}`
logger.info(msg)
} catch (error) {
logger.error(error)
process.exit(1)
}
}
start()v2 Generic KO format sample
{
"payload": {
"data": "test data for Generic KO."
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>"
},
"metadata": {
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"public": true
}
}Available endpoints - V2 Generic KOs
POST <hostname:port>/api/v2/knowledge
This is the endpoint for adding a new knowledge object.
Example JSON body
{
"payload": {
"data": "test data for Generic KO"
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": true
}
}Example curl command
curl -X POST -H "Content-Type: application/json" -d '{
"payload": {
"data": "test data for Generic KO"
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": true
}
}' http://localhost:3111/api/v2/knowledgeExample JSON Response
{
"id": "clmzsbakr0003sko1gmf13z74",
"ko": {
"id": "clmzsbakq0002sko1vnevlt6i",
"name": "Generic KO mandatory fields with description",
"ownerId": "clmzsbaki0001sko1dasym0p7",
"latestVersionId": "clmzsbakr0003sko1gmf13z74",
"latestPublishedVersionId": "clmzsbakr0003sko1gmf13z74",
"banned": false,
"type": "application/vnd.acme.app.analytic"
},
"owner": {
"id": "clmzsbaki0001sko1dasym0p7",
"name": "John Smith",
"email": "[email protected]",
"emailHash": "b17827239fa3b1d4eb667590c4c0e3d3",
"role": "USER",
"username": "johnsmith349",
"isOrg": false
}
}GET <hostname:port>/api/v2/knowledge
This is the endpoint for checking if a knowledge object exists based on specified query parameters: name, type and email.
Example curl command
curl -X GET "http://localhost:3111/api/v2/knowledge?name=Generic%20KO%20mandatory%20fields%20with%20description&type=application%2Fvnd.acme.app.analytic&email=john.smith%40example.com"Example response with status code 200
{
"message": "Knowledge found."
}Example response with status code 404
{
"message": "Knowledge not found."
}PUT <hostname:port>/api/v2/knowledge/:id
This is the endpoint for editing an existing knowledge object. The version id (:id) must target the latest id to succeed.
Example JSON body
{
"payload": {
"data": "test data for Generic KO. Changed Data."
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>. Or Changed Description"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": true
}
}Example curl command
curl -X PUT \
-H "Content-Type: application/json" -d '{
"payload": {
"data": "test data for Generic KO. Changed Data."
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>. Or Changed Description"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": true
}
}' \
http://localhost:3111/api/v2/knowledge/cln13uepr0003skt5fyi5vdmkExample JSON Response
{
"id": "cln14qm6l0007skt5pxzunjym",
"koId": "cln13uepr0002skt5zql54v5k",
"createdNewVersion": true
}A new version is created when the payload or description changes. Changing public flag will not create a new version.
Changing public flag from true to false is not allowed when KO is under verification review. Example JSON Response when attempting to unpublish and the KO is under verification review.
{
"message": "Knowledge could not be unpublished since it has already been accepted by a verifier."
}Changing public flag from false to true is allowed when KO is under verification review.
POST <hostname:port>/api/v2/knowledge/:id/publish
This is the endpoint for publishing an existing knowledge object.
Example curl command
curl -X POST http://localhost:3111/api/v2/knowledge/cln14qm6l0007skt5pxzunjym/publishExample JSON response
{
"id": "cln14qm6l0007skt5pxzunjym",
"publishedStatus": "PUBLISHED",
"verifiedStatus": "PENDING"
}Example JSON response if already published (HTTP 409)
{
"message": "Knowledge is already published with a verified status of PENDING"
}Example JSON response if unpublished version is already rejected by a verifier (HTTP 409)
{
"message": "Knowledge could not be published since it has already been rejected by a verifier."
}POST <hostname:port>/api/v2/knowledge/:id/unpublish
This is the endpoint for unpublishing an existing knowledge object.
Example curl command
curl -X POST http://localhost:3111/api/v2/knowledge/cln14qm6l0007skt5pxzunjym/unpublishExample JSON response
{
"id": "cln14qm6l0007skt5pxzunjym",
"publishedStatus": "UNPUBLISHED",
"verifiedStatus": "PENDING"
}Example JSON response if already unpublished (HTTP 409)
{
"message": "Knowledge is already unpublished"
}Example JSON response if KO is being reviewed or accepted by a verifier
{
"message": "Knowledge could not be unpublished since it has already been accepted by a verifier."
}POST <hostname:port>/api/v2/knowledge/publish
This is the endpoint for publishing the latest knowledge object version. To publish a previous version, use the above publish endpoint that targets a particular knowledge version id.
Example JSON body
{
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"metadata": {
"owner": {
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description"
}
}Example curl command
curl -X POST \
-H "Content-Type: application/json" -d '{
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"metadata": {
"owner": {
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description"
}
}' \
http://localhost:3111/api/v2/knowledge/publishExample JSON response
{
"id": "cln14qm6l0007skt5pxzunjym",
"publishedStatus": "PUBLISHED",
"verifiedStatus": "PENDING"
}POST <hostname:port>/api/v2/knowledge/unpublish
This is the endpoint for unpublishing the latest knowledge object version. To publish a previous version, use the above unpublish endpoint that targets a particular knowledge version id.
Example JSON body
{
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"metadata": {
"owner": {
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description"
}
}Example curl command
curl -X POST \
-H "Content-Type: application/json" -d '{
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"metadata": {
"owner": {
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description"
}
}' \
http://localhost:3111/api/v2/knowledge/unpublishExample JSON response
{
"id": "cln14qm6l0007skt5pxzunjym",
"publishedStatus": "UNPUBLISHED",
"verifiedStatus": "PENDING"
}GET <hostname:port>/api/v2/knowledge/:id
This is the endpoint for fetching the knowledge object version by version id.
Example curl command
curl http://localhost:3111/api/v2/knowledge/cln14qm6l0007skt5pxzunjymExample JSON response
{
"payload": {
"data": "test data for Generic KO. Changed Data."
},
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>. Or Changed Description"
},
"metadata": {
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"public": false,
"id": "http://localhost:3000/knowledge/cln14qm6l0007skt5pxzunjym/json",
"source": "http://localhost:3000",
"knowledgeObjectId": "cln13uepr0002skt5zql54v5k",
"knowledgeObjectVersionId": "cln14qm6l0007skt5pxzunjym"
}
}GET <hostname:port>/api/v2/knowledge/:id/:attribute
This is the endpoint for fetching the 'payload', 'environment', 'description' or 'metadata' attribute of the knowledge object version by version id.
Example curl command
curl http://localhost:3111/api/v2/knowledge/cln14qm6l0007skt5pxzunjym/payloadExample JSON response
{
"data": "test data for Generic KO. Changed Data."
}GET <hostname:port>/api/v2/knowledge/search?q=:query&p=:page&type=:type
This is the search endpoint for querying knowledge object versions.
Query Parameters
| Param | Description | Example |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| q | The query string. Searches against KO name, KOV description, KO owner and contributor names and usernames. If not specified, all KOVs will match. | q=foobar |
| type | Filter by the knowledge object type. Multiple types may be specified, returning all KOVs with that type | type=application%2Fvnd.acme.app.analytic |
| p | Specify which page to return. Defaults to 1. | p=2 |
| searchAttributes.<attribute> | Filter by search attribute. Each search attribute may be specified only once. | searchAttributes.foo=bar&searchAttributes.baz=qux |
| prerequisites.<attribute> | Filter by prerequisites in the same manner as search attributes | prerequisites.foo=bar&prerequisites.baz=qux |
Example with no query params
curl http://localhost:3111/api/v2/knowledge/searchExample JSON Response
{
"total": {
"value": 2,
"relation": "eq"
},
"pages": 1,
"page": 1,
"results": [{
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>. Or Changed Description"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": false,
"id": "http://localhost:3000/knowledge/cln14qm6l0007skt5pxzunjym/json",
"knowledgeObjectId": "cln13uepr0002skt5zql54v5k",
"knowledgeObjectVersionId": "cln14qm6l0007skt5pxzunjym",
"source": "http://localhost:3000"
}
}, {
"environment": {
"type": "application/vnd.acme.app.analytic"
},
"description": {
"html": "<h1>Generic KO mandatory fields with description</h1> <div>Hello World</div>"
},
"metadata": {
"owner": {
"name": "John Smith",
"email": "[email protected]"
},
"name": "Generic KO mandatory fields with description",
"about": "Short text to be displayed in the abstract of KO Page. This is optional",
"public": true,
"id": "http://localhost:3000/knowledge/cln13uepr0003skt5fyi5vdmk/json",
"knowledgeObjectId": "cln13uepr0002skt5zql54v5k",
"knowledgeObjectVersionId": "cln13uepr0003skt5fyi5vdmk",
"source": "http://localhost:3000"
}
}]
}