Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/artcom/acms-api

Manipulate content of JSON files in a git repository via HTTP. API for https://github.com/artcom/acms-compose.
https://github.com/artcom/acms-api

Last synced: 3 months ago
JSON representation

Manipulate content of JSON files in a git repository via HTTP. API for https://github.com/artcom/acms-compose.

Host: GitHub
URL: https://github.com/artcom/acms-api
Owner: artcom
License: mit
Created: 2021-03-15T16:48:06.000Z (almost 4 years ago)
Default Branch: master
Last Pushed: 2022-12-22T02:06:02.000Z (about 2 years ago)
Last Synced: 2024-09-18T05:32:23.566Z (5 months ago)
Language: JavaScript
Homepage:
Size: 836 KB
Stars: 3
Watchers: 9
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# ACMS API

A JSON API to serve the contents of JSON files from a Git repo. All files in the repo are expected to be JSON files with a `.json` extension.

## Configuration

### Environment Variables

The service uses the following environment variables:

* `REPO_URI` _(required)_ URI of the Git repository
* `SIGNATURE_MAIL` _(optional)_ E-mail address used for generated commits
* `REPO_TOKEN` _(optional)_ Token for accessing private repo
* `ACMS_API_VAR_*`_(optional)_ A list of variables to be replaced in the content (see "Variable Replacement" for details)

### Variable Replacement

The service replaces variables in files when serving and writing. All variables need to be environment variables prefixed with `ACMS_API_VAR_`. Example:
```
export ACMS_API_VAR_MY_FANCY_VARIABLE="value"
```

If a variable occurs in the content it will be replaced by the given value. When writing to the repo values will also be replaced by their variable name.

**Example**
```
Content: "Hello ${properGreeting}."
ACMS_API_VAR_PROPER_GREETING: "World"
Served: "Hello World."
````

## API

### `GET /:version`

Returns the contents of the repo at the given version as a single JSON object.

Version can either be a Git commit hash or a reference. The response will contain the Git commit hash in the `Git-Commit-Hash` header.

The returned object contains the contents of every file in the root of the repo in a property named like the file (without extension). For every directory, it contains another object with the same structure.

If a repo contains `file1.json`, `file2.json`, `directory/fileA.json` and `directory/subDirectory/fileB.json`, the response would be structured as follows:

```json5
// GET /master
{
"directory" : {
"fileA": {
"foo": "bar"
},
"subDirectory": {
"fileB": {
"foo": "bar"
}
}
},
"file1": {
"min": 1,
"max": 10
},
"file2": [
"item1",
"item2",
"item3"
]
}
```

### `GET /:version/path`

Optionally, the previous route can be called with an additional path into the content to retrieve specific data.

```json5
// GET /master/directory/fileA
{
"foo": "bar"
}
```

### `GET /:version/path?listFiles=true`

The `listFiles` parameter returns a flat structure with every file in `path` and in subdirectories where the file path is the `key` and the file content the `value`.

```json5
// GET /master/directory?listFiles
{
"file1":
{
"foo": "bar"
},
"file2": [1, 2, 3],
"subDirectory/file3": "foo"
}
```

### `PUT /:version/path`

The content of a directory or single file can be replaced using a PUT request. The body is expected to contain JSON data for all files and subdirectories or a file. The intended workflow is to query a path using `GET /:version/path`, make the desired changes to the data and send the whole data back via `PUT /:parentVersion/path`.

A new Git commit will be created and merged if necessary. The response will contain the hash of the new (merge) commit in the `Git-Commit-Hash` header. If the merge fails, an error will be returned.

#### Examples

The body to replace everything inside directory looks like this:

```json5
// PUT /master/directory
{
"files": {
"fileA": {
"foo": "bar"
},
"subDirectory/fileB": {
"foo": "bar"
}
}
}
}
```

The body to replace a single file only looks like this:
```json5
// PUT /master/file1
{
"fileContent" : {
"min": 10,
"max": 30
}
}
```

Additional properties are:
`author`: Will be used as commit author.
`updateBranch`: The branch which should be updated to the new commit (default: "master").

### `DELETE /:version/path`

A directory or a single file can be deleted using a DELETE request. The body is expected to contain JSON data containing a `file` or `directory` property.

A new Git commit will be created and merged if necessary. The response will contain the hash of the new (merge) commit in the `Git-Commit-Hash` header. If the merge fails, an error will be returned.

#### Examples

Delete single file:
```json5
// DELETE /master/parentDirectory
{
"file": "fileToDelete"
}
```

Delete a directory:
```json5
// DELETE /master/parentDirectory
{
"directory": "directoryToDelete"
}
```

Additional properties are:
`author`: Will be used as commit author.
`updateBranch`: The branch which should be updated to the new commit (default: "master").

## Development Setup

```bash
npm install
REPO_URI= npm run watch
```

## Deployment

### Heroku/Dokku

The service is designed to be deployed using [Dokku](http://dokku.viewdocs.io/dokku/) and will probably also work with [Heroku](https://www.heroku.com/) and other compatible platforms.

### Dockerfile

The service contains a Dockerfile to start it directly with Docker.

## Troubleshooting
On Mac OS if you encounter this error: `error: no template named 'remove_cv_t' in namespace 'std'; did you mean 'remove_cv'?` when running `npm install` with node 16 try: `export CXXFLAGS="--std=c++17" && npm install` (see this node-gyp [issue](https://github.com/nodejs/node-gyp/issues/2387)).