Skip to content

Commit 8a7ea7d

Browse files
rubenvdlinderubenvdlinde
committed
Lets add docusaurus
1 parent 12069a5 commit 8a7ea7d

File tree

6 files changed

+455
-11
lines changed

6 files changed

+455
-11
lines changed

‎.github/workflows/documentation.yml

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- documentation
7+
pull_request:
8+
branches:
9+
- documentation
10+
11+
jobs:
12+
deploy:
13+
name: Deploy Documentation
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
steps:
18+
- uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: 18
26+
cache: npm
27+
28+
- name: Install dependencies
29+
run: |
30+
cd website
31+
npm ci
32+
33+
- name: Build website
34+
run: |
35+
cd website
36+
npm run build
37+
38+
# Deploy to GitHub Pages
39+
- name: Deploy to GitHub Pages
40+
uses: peaceiris/actions-gh-pages@v3
41+
if: github.ref == 'refs/heads/documentation'
42+
with:
43+
github_token: ${{ secrets.GITHUB_TOKEN }}
44+
publish_dir: ./website/build
45+
user_name: github-actions[bot]
46+
user_email: 41898282+github-actions[bot]@users.noreply.github.com
47+
48+
# Notify on failure
49+
- name: Notify on failure
50+
if: failure()
51+
uses: actions/github-script@v6
52+
with:
53+
script: |
54+
github.rest.issues.create({
55+
owner: context.repo.owner,
56+
repo: context.repo.repo,
57+
title: 'Documentation build failed',
58+
body: 'The documentation build failed. Please check the workflow logs.'
59+
})

‎README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Open Registers
22

3-
Open Registers provides the ability to work with objects based on [`schema.json`](https://json-schema.org/).
3+
Open Registers provides a way to quicly build and deploy standardized registers based on [NLGov REST API Design Rules](https://logius-standaarden.github.io/API-Design-Rules/) and [Common Ground Principles](https://common-ground.nl/common-ground-principes/). It is based on based on the concepts of defining object types in [`schema.json`](https://json-schema.org/) and storing objects in configurable source.
44

55
## What is Open Registers?
66

@@ -12,7 +12,7 @@ Registers provide APIs for consumption.
1212

1313
Registers can also apply additional logic to objects, such as validation that is not applicable through the [`schema.json`](https://json-schema.org/) format.
1414

15-
## Features
15+
## Key Features
1616

1717
- 📦 **Object Management**: Work with objects based on [`schema.json`](https://json-schema.org/).
1818
- 🗂️ **Register System**: Manage collections of object types.
@@ -60,7 +60,7 @@ Open Register makes these principles accessible to any organization by providing
6060

6161
| Feature | Description | Benefits |
6262
|---------|-------------|-----------|
63-
| 💾 [Object Storage](docs/object-storage.md) | Flexible storage backend selection per register | Storage flexibility, system integration, scalability |
63+
| 💾 [Storing Objects](docs/storing-objects.md) | Configure how and where register data is stored | Storage flexibility, system integration, scalability |
6464
| 📝 [Audit Trails](docs/audit-trails.md) | Complete history of all object changes | Compliance, accountability, change tracking |
6565
| ⏰ [Time Travel](docs/time-travel.md) | View and restore previous object states | Data recovery, historical analysis, version control |
6666
| 🔒 [Object Locking](docs/object-locking.md) | Prevent concurrent modifications | Data integrity, process management, conflict prevention |
@@ -75,7 +75,7 @@ Open Register makes these principles accessible to any organization by providing
7575
| ⚡ [Elasticsearch](docs/elasticsearch.md) | Advanced search and analytics capabilities | Performance, insights, complex queries |
7676
| 📋 [Schema Import & Sharing](docs/schema-import.md) | Import schemas from Schema.org, OAS, GGM, and share via Open Catalogi | Standards compliance, reuse, collaboration |
7777
| 🔔 [Events & Webhooks](docs/events.md) | React to object changes with events and webhooks | Integration, automation, real-time updates |
78-
| 🔄 [Data Extension](docs/data-extension.md) | Automatically include related entities in responses | Efficient data retrieval, reduced API calls, complete context |
78+
| 🔄 [Data Extension](docs/data-extension.md) | Include related entities in responses using _extend | Reduced API calls, complete context, efficient data retrieval |
7979
| ✂️ [Data Filtering](docs/data-filtering.md) | Select specific properties to return | Data minimalization, GDPR compliance, efficient responses |
8080
| 🔍 [Advanced Search](docs/advanced-search.md) | Filter objects using flexible property-based queries | Precise filtering, complex conditions, efficient results |
8181
| 🗑️ [Object Deletion](docs/object-deletion.md) | Soft deletion with retention and recovery | Data safety, compliance, lifecycle management |

‎docs/data-extension.md

Lines changed: 96 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,104 @@
11
# Data Extension (_extend)
22

3-
Data Extension allows you to automatically include related entities in API responses, reducing the need for multiple API calls and providing complete context in a single request.
3+
Data Extension allows you to automatically include related entities in API responses, reducing the need for multiple API calls and providing complete context in a single request. This is useful when you need to retrieve related data for a specific object or collection an lowers the number of API calls needed therby reducing the load on the server and improving performence client side.
4+
5+
The extend patern is based was orginally developed for the [Open Catalogi](https://opencatalogi.org) project and is now available in the ObjectStore API. Its baed on the extend functionality of [Zaak gericht werken] but brought in line with p[NLGov REST API Design Rules](https://logius-standaarden.github.io/API-Design-Rules/) by adding a _ prefix to the parameter
6+
47

58
## Overview
69

7-
The _extend parameter provides:
8-
- Automatic inclusion of related entities
9-
- Support for nested relations
10-
- Resolution of both ID and URL references
11-
- Configurable depth limits
12-
- Circular reference handling
10+
The extension system provides:
11+
- Automatic inclusion of related objects
12+
- Nested object resolution
13+
- Circular reference protection
14+
- Depth limiting
15+
- Performance optimization
16+
17+
## Extension Patterns
18+
19+
### Basic Extension
20+
Extend a single property:
21+
- `?_extend=author` - Include full author object
22+
- `?_extend=category` - Include full category object
23+
- `?_extend=files` - Include file metadata
24+
25+
### Nested Extension
26+
Extend nested properties:
27+
- `?_extend=author.organization` - Include author with their organization
28+
- `?_extend=department.employees` - Include department with all employees
29+
- `?_extend=project.tasks.assignee` - Include project with tasks and their assignees
30+
31+
### Multiple Extensions
32+
Combine multiple extensions:
33+
- `?_extend=author,category,comments` - Include multiple related objects
34+
- `?_extend=files,metadata,relations` - Include all related data
35+
- `?_extend=all` - Include all possible relations on the root object
36+
37+
## Extension Logic
38+
39+
1. **Depth Control**
40+
- Maximum depth of 3 levels
41+
- Prevents infinite recursion
42+
- Optimizes response size
43+
- Manages performance
44+
45+
2. **Circular Detection**
46+
- Identifies circular references
47+
- Prevents infinite loops
48+
- Maintains data integrity
49+
- Optimizes response
50+
51+
3. **Type Handling**
52+
- Single object relations
53+
- Array of objects
54+
- File references
55+
- External references
56+
57+
## Performance Considerations
58+
59+
1. **Query Optimization**
60+
- Efficient database queries
61+
- Batch loading
62+
- Cache utilization
63+
- Resource management
64+
65+
2. **Response Size**
66+
- Selective extension
67+
- Depth limiting
68+
- Data filtering
69+
- Compression
70+
71+
3. **Caching**
72+
- Response caching
73+
- Relation caching
74+
- Cache invalidation
75+
- Cache optimization
76+
77+
## Best Practices
78+
79+
1. **Extension Selection**
80+
- Request only needed relations
81+
- Consider response size
82+
- Use appropriate depth
83+
- Plan for performance
84+
85+
2. **Query Design**
86+
- Use specific extensions
87+
- Combine related requests
88+
- Optimize query patterns
89+
- Consider caching
90+
91+
3. **Error Handling**
92+
- Handle missing relations
93+
- Validate extension paths
94+
- Manage timeouts
95+
- Provide fallbacks
96+
97+
## Related Features
98+
99+
- [Object Relations](object-relations.md) - Base for extensions
100+
- [Data Selection](data-selection.md) - Combine with property selection
101+
- [Content Search](content-search.md) - Search within extended data
13102

14103
## Extension Types
15104

‎docs/storing-objects.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Storing Objects
2+
3+
Open Register provides flexible storage options for objects, allowing organizations to store their data in various backends while maintaining a consistent interface.
4+
5+
## Overview
6+
7+
The storage system supports:
8+
- Multiple storage backends
9+
- Transparent data access
10+
- Unified querying interface
11+
- Consistent audit logging
12+
- Schema validation across stores
13+
14+
## Storage Options
15+
16+
### Nextcloud Internal Store (Default)
17+
Default storage using Nextcloud's database:
18+
- Objects stored as JSON in MariaDB/MySQL
19+
- Full CRUD operations
20+
- Built-in versioning
21+
- Automatic audit trails
22+
- Integrated with Nextcloud permissions
23+
24+
### Relational Databases
25+
Traditional SQL databases:
26+
- MariaDB/MySQL
27+
- PostgreSQL
28+
- JSON column types
29+
- SQL query optimization
30+
- Transaction support
31+
32+
### Document Stores
33+
NoSQL databases optimized for JSON documents:
34+
- MongoDB support
35+
- Native JSON storage
36+
- Schema-less flexibility
37+
- High performance queries
38+
- Scalable architecture
39+
40+
### EAV (Entity-Attribute-Value)
41+
Integration with systems like "Uit Betrouwbare Bron":
42+
- Dynamic attribute storage
43+
- Flexible schema support
44+
- Legacy system compatibility
45+
- Custom attribute mapping
46+
- Historical data support
47+
48+
## Storage Configuration
49+
50+
Each register defines:
51+
- Storage backend type
52+
- Connection details
53+
- Schema mapping
54+
- Query optimization
55+
- Cache settings
56+
57+
## Implementation Details
58+
59+
### Internal Store
60+
```sql
61+
CREATE TABLE objects (
62+
id INT PRIMARY KEY,
63+
uuid VARCHAR(255),
64+
object JSON,
65+
metadata JSON
66+
)
67+
```
68+
69+
### Document Store
70+
```json
71+
{
72+
"_id": "object_id",
73+
"uuid": "unique_id",
74+
"object": {
75+
"property": "value"
76+
},
77+
"metadata": {
78+
"created": "timestamp"
79+
}
80+
}
81+
```
82+
83+
### Relational Store
84+
```sql
85+
CREATE TABLE objects (
86+
id INT PRIMARY KEY,
87+
uuid VARCHAR(255),
88+
data JSONB,
89+
created_at TIMESTAMP
90+
)
91+
```
92+
93+
### EAV Store
94+
```sql
95+
CREATE TABLE object_values (
96+
object_id INT,
97+
attribute VARCHAR(255),
98+
value TEXT,
99+
PRIMARY KEY (object_id, attribute)
100+
)
101+
```
102+
103+
## Key Benefits
104+
105+
1. **Flexibility**
106+
- Choose optimal storage per register
107+
- Match existing infrastructure
108+
- Scale independently
109+
- Custom implementations
110+
111+
2. **Integration**
112+
- Legacy system support
113+
- Multiple databases
114+
- External systems
115+
- Distributed storage
116+
117+
3. **Performance**
118+
- Storage optimization
119+
- Query efficiency
120+
- Caching strategies
121+
- Scalability options
122+
123+
## Best Practices
124+
125+
1. **Storage Selection**
126+
- Consider data structure
127+
- Evaluate query patterns
128+
- Assess volume requirements
129+
- Plan for growth
130+
131+
2. **Configuration**
132+
- Optimize connections
133+
- Set up caching
134+
- Configure backups
135+
- Monitor performance
136+
137+
3. **Management**
138+
- Regular maintenance
139+
- Performance monitoring
140+
- Security updates
141+
- Backup verification
142+
143+
## Related Features
144+
145+
- [Schema Validation](schema-validation.md) - Validate across storage types
146+
- [Audit Trails](audit-trails.md) - Track changes in all stores
147+
- [Content Search](content-search.md) - Search across stores
148+
- [Object Relations](object-relations.md) - Relations across stores

0 commit comments

Comments
 (0)