You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .claude/CLAUDE.md
-239Lines changed: 0 additions & 239 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,224 +6,6 @@ This file provides guidance to AI assistants when working with code in this repo
6
6
7
7
RERUM API v1 is an open source Node.js/Express RESTful API server for the RERUM digital object repository. It stores any valid JSON object but prefers JSON-LD objects such as Web Annotations (https://www.w3.org/TR/annotation-model/) and IIIF Presentation API (https://iiif.io/api/presentation/3.0/) resources. The system emphasizes open access, attribution, versioning, and compliance with Linked Data standards. It's responses follow RESTful best practices (https://restfulapi.net/http-status-codes/). It is maintained by the Research Computing Group at Saint Louis University (https://www.slu.edu/research/faculty-resources/research-computing/index.php).
8
8
9
-
It is hosted on the web as a centralized API using a centralized database that many applications read from and write to concurrently. It promotes and encourages open source development, and can be a cheap option as an API and back end for a web application. A sanbox API and client application called TinyThings (https://tiny.rerum.io) gives developers an easy rapid prototyping option. That repo can be found at https://github.com/CenterForDigitalHumanities/TinyNode.
10
-
11
-
Users register with the RERUM API by signing up through Auth0. This will generate a refresh token and an access token for those who sign up. The access token is used as the Bearer Token on requests, which the RERUM API can then use to authenticate the request is from a registered RERUM application. The refresh token can be used to get new access tokens through the RERUM API. All data created and updated gets a `__rerum.generatedBy` property that is an Agent URI encoded in that token. In this way, all data created an updated is attributed to specific application. The API encourages applications to go a step further and attribute data to specific users with a user system and a `creator` property.
12
-
13
-
In production and development it is registered in a pm2 instance running on a 4-core RHEL VM. It is started with `pm2 start -i max`, and so load balances across 4 instances. The MongoDB that stores all the data is hosted through MongoDB Atlas. The .github folder contains CI/CD for production and development deployment pipelines.
14
-
15
-
16
-
**Key Principles:**
17
-
- Save an object, retrieve an object—metadata lives in private `__rerum` property
18
-
- Trust the application, not the user—Auth0 JWT tokens for write operations
19
-
- Open and Free—no charge to read or write, all contributions exposed immediately
20
-
- Attributed and Versioned—all objects track ownership and transaction history
21
-
22
-
## Development Commands
23
-
24
-
### Setup and Installation
25
-
```bash
26
-
npm install # Install dependencies (2-5 seconds)
27
-
```
28
-
29
-
### Running the Application
30
-
```bash
31
-
npm start # Start server (http://localhost:3001 by default)
32
-
```
33
-
34
-
### Testing
35
-
```bash
36
-
npm run runtest # Run full test suite (25+ minutes, requires MongoDB)
37
-
npm run runtest -- __tests__/routes_mounted.test.js # Run route mounting tests (30 seconds, no DB needed)
38
-
npm run runtest -- routes/__tests__/create.test.js # Run specific test file
39
-
```
40
-
41
-
**Important:** Use `npm run runtest` (not `npm test`) as it enables experimental VM modules required for ES6 imports in Jest.
42
-
43
-
### Development Workflow
44
-
```bash
45
-
# After making routing changes
46
-
npm run runtest -- __tests__/routes_mounted.test.js
47
-
48
-
# Test server startup
49
-
npm start # Should display "LISTENING ON 3001" (or configured PORT)
50
-
51
-
# In another terminal, test endpoints
52
-
curl -I http://localhost:3001/v1/API.html
53
-
curl -X POST http://localhost:3001/v1/api/query -H "Content-Type: application/json" -d '{"test":"value"}'
54
-
```
55
-
56
-
## Architecture
57
-
58
-
### High-Level Structure
59
-
60
-
The application follows a **layered architecture** with clear separation of concerns:
/app.js Express app setup and middleware configuration
131
-
/db-controller.js Controller facade exporting all operations
132
-
```
133
-
134
-
## Important Patterns and Conventions
135
-
136
-
### 1. __rerum Property Management
137
-
Never trust client-provided `__rerum` data. Always use `utils.configureRerumOptions()` to set:
138
-
-`APIversion`, `createdAt`, `generatedBy`
139
-
-`history`: {prime, previous, next[]}
140
-
-`releases`: {previous, next[], replaces}
141
-
-`isOverwritten`, `isReleased`, `slug`
142
-
143
-
### 2. ID Handling
144
-
Objects have both MongoDB `_id` and JSON-LD `@id` or `id`:
145
-
-`_id`: MongoDB ObjectId (or slug if provided)
146
-
-`@id`: Full URI like `{RERUM_ID_PREFIX}{_id}`
147
-
- Use `idNegotiation()` to handle @context variations (some contexts prefer `id` over `@id`)
148
-
- Use `parseDocumentID()` to extract _id from full URIs
149
-
150
-
### 3. Error Handling
151
-
- Use `createExpressError(err)` from controllers/utils.js to format errors
152
-
- Let errors propagate to `rest.js` messenger middleware—don't res.send() in controllers
153
-
- Messenger adds helpful context based on status code (401, 403, 404, 405, 409, 500, 503)
154
-
155
-
### 4. Headers
156
-
- Use `utils.configureWebAnnoHeadersFor(obj)` for single objects (Content-Type, Link, Allow)
157
-
- Use `utils.configureLDHeadersFor(obj)` for arrays/query results
158
-
- Use `utils.configureLastModifiedHeader(obj)` for caching support
159
-
- Always set Location header on 201 Created responses
160
-
161
-
### 5. Maintenance Mode
162
-
Check `process.env.DOWN` and `process.env.READONLY`:
163
-
- DOWN="true": Return 503 for all requests
164
-
- READONLY="true": Block write operations (create/update/delete) with 503
165
-
166
-
### 6. Versioning Logic
167
-
When updating (PUT/PATCH):
168
-
1. Clone original object with its @id
169
-
2. Pass to `configureRerumOptions(generator, cloned, true, false)`
170
-
3. Insert as new object with new _id
171
-
4. Update original's `history.next[]` array to include new version's @id
172
-
5. Never modify released objects (isReleased check)
173
-
174
-
### 7. Deleted Objects
175
-
Deleted objects are transformed: `{"@id": "{id}", "__deleted": {original object properties, "time": ISO-date}}`. The history trees there were a part of are healed to remain connected (this cannot be undone). They are removed from /query and /search results, but deleted objects can always be retrieved by the URI id and will be returned in their deleted form.
0 commit comments