aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: c229152368c86a946621350daa72339a1c119561 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
# GN4 Guile Webservice

This directory provides a Guile web service incl. the new REST API. It is used in conjunction with the Python web services and (very much) WIP.

# Documentation

Start with this file and then the documentation in [doc](./doc/gn-guile.md).

# Development

The current repository lives at

```sh
git clone tux02.genenetwork.org:/home/git/public/gn-guile
```

GNU Guile allows you to develop against a live running web server using emacs-geiser. To try this fire up the web server from the `web` directory as

```sh
cd web
unset GUIX_PROFILE
. .guix-shell -- guile -L .. --listen=1970 -e main ./webserver.scm 8091
```

Note the leading dot. The .guix-shell is defined in `gn-guile/web` and loads required packages using GNU Guix.
If you are on Debian you may need to unset GUIX_PROFILE first.

Next fire up emacs with `emacs-geiser-guile` and connect to the running web server with `M-x geiser-connect` and the port `1970`. Now you can not only inspect procedures, but also update any prodedure on the live server using `C-M-x` and get updated output from the webserver!

# Tools

Some tooling and scripts that run independently are stored in `./scripts`.

Here’s the entire markdown content combined into a single, copyable file:


# Gn-Markdown

Gn-Markdown is an API endpoint to edit, parse, and commit markdown files for gn-docs.

## How to Test the APIs

1. **Navigate to the Web Directory and Start the Server**

    ```sh
    cd web
    . .guix-shell -- guile -L .. --listen=1970 -e main ./webserver.scm 8091
    ```

2. **Test Endpoints**

    The main endpoints provided are `/edit` and `/commit`. More endpoints may be added in the future.

## Edit (GET)

This is a GET request to retrieve a file's details.

**Request Example:**

```
localhost:8091/edit?file_path=test.md
```

**Expected Success Response:**

```json
{
    "path": "test.md",
    "content": "Test for new user\n test 2 for line\n test 3 for new line\n ## real markdown two test\n",
    "hash": "ecd96f27c45301279150fbda411544687db1aa45"
}
```

**Expected Error Response (Status 400):**

```json
{
    "error": "file-error",
    "msg": "The file path /home/kabui/test_repo/test.md does not exist"
}
```

## Commit (POST)

This is a POST request to commit changes to a file.

**Request URL:**

```
localhost:8091/commit
```

**Request Body Example:**

```json
{
    "content": "Test for new user\n test 2 for line\n test 3 for new line\n ## real markdown two test\n",
    "filename": "test.md",
    "username": "genetics",
    "email": "genetics@gmail.com",
    "commit": "commit by genetics"
}
```

**Expected Success Response:**

```json
{
    "status": "201",
    "message": "Committed file successfully",
    "content": "Test for new user\n test 2 for line\n test 3 for new line\n ## real markdown two test\n",
    "commit-sha": "47df3b7f13a935d50cc8b40e98ca9e513cba104c",
    "commit-message": "commit by genetics"
}
```

**If No Changes to File:**

```json
{
    "status": "200",
    "message": "Nothing to commit, working tree clean",
    "commit-sha": "ecd96f27c45301279150fbda411544687db1aa45"
}
```

**Expected Error Response:**

```json
{
    "error": "system-error",
    "msg": "Commits do not match. Please pull in the latest changes for the current commit *ecd96f27c45301279150fbda411544687db1aa45* and previous commits."
}
```

# Development

```
git remote add gn git.genenetwork.org:/home/git/public/gn-guile
```

# LICENSE

This software is published by the GeneNetwork team under the AGPL3. See [LICENSE](LICENSE.txt).