-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #422 from codenotary/chore_update_doc
Chore update doc
- Loading branch information
Showing
12 changed files
with
396 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,259 @@ | ||
| # API | ||
|
|
||
| ::: tip | ||
| By default, Swagger UI is enabled and can be accessed at `http://localhost:8080/api/docs/` | ||
| ::: | ||
|
|
||
| <WrappedSection> | ||
|
|
||
| ## Authentication | ||
|
|
||
| A session must be active in order for you to be able to access collection and document endpoints. | ||
|
|
||
| ### Open session | ||
|
|
||
| In the following script, the default credentials are used to open a session in the defaultdb database. | ||
|
|
||
| A sessionID is assigned by immudb, and this value must be included in all subsequent requests. | ||
|
|
||
| ```bash | ||
| sessionid=$( | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/authorization/session/open' \ | ||
| -H 'accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "username": "immudb", | ||
| "password":"immudb", | ||
| "database":"defaultdb" | ||
| }' | jq -r .sessionID) | ||
| ``` | ||
|
|
||
|
|
||
| ### Close session | ||
|
|
||
| Although immudb automatically closes inactive sessions, it is a good practice to explicitly close sessions when they are not needed anymore in order to free up resources immediately. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/authorization/session/close' -H "sessionID: $sessionid" | ||
| ``` | ||
|
|
||
| </WrappedSection> | ||
|
|
||
| <WrappedSection> | ||
|
|
||
| ## Collections | ||
|
|
||
| Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data. | ||
|
|
||
| ### Create collection | ||
|
|
||
| Any json object can be stored in a collection, but declared fields enable indexes to be created. | ||
|
|
||
| Here is the script that creates a collection with two fields of type `STRING` and a non-unique index over one of them. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "fields": [ | ||
| {"name": "name", "type": "STRING"}, | ||
| {"name": "surname", "type": "STRING"} | ||
| ], | ||
| "indexes": [ | ||
| {"fields": ["name"], "unique": "false"} | ||
| ] | ||
| }' | ||
| ``` | ||
|
|
||
| ### Delete collection | ||
|
|
||
| It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed. | ||
|
|
||
| ```bash | ||
| curl -X 'DELETE' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection' \ | ||
| -H "sessionID: $sessionid" | ||
| ``` | ||
|
|
||
| </WrappedSection> | ||
|
|
||
| <WrappedSection> | ||
|
|
||
| ## Indexes | ||
|
|
||
| Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data. | ||
|
|
||
| ### Create index | ||
|
|
||
| It is possible to create indexes over the declared fields in the collection. | ||
|
|
||
| Creating non-unique indexes is possible at any time, while creating unique ones is only possible when no documents have been stored. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/index' \ | ||
| -H 'accept: application/json' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "fields": [ | ||
| "surname" | ||
| ] | ||
| }' | ||
| ``` | ||
|
|
||
| ### Delete index | ||
|
|
||
| It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed. | ||
|
|
||
| ```bash | ||
| curl -X 'DELETE' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/index?fields=surname' \ | ||
| -H "sessionID: $sessionid" | ||
| ``` | ||
|
|
||
| </WrappedSection> | ||
|
|
||
| <WrappedSection> | ||
|
|
||
| ## Documents | ||
|
|
||
| Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data. | ||
|
|
||
| ### Insert document | ||
|
|
||
| Single or multiple documents can be inserted in a single request | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/documents' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "documents": [ | ||
| {"name":"John", "surname":"Doe"}, | ||
| {"name":"Jane", "surname":"Smith"} | ||
| ] | ||
| }' | ||
| ``` | ||
|
|
||
| ### Search documents | ||
|
|
||
| It is possible to delete collections, and the physical removal of any declared index will be carried out. The raw data in the transaction commit log have not been altered, but this operation cannot be reversed. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/documents/search' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'accept: application/json' \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "query": { | ||
| "expressions": [ | ||
| { | ||
| "fieldComparisons": [ | ||
| { | ||
| "field": "name", | ||
| "operator": "EQ", | ||
| "value": "John" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| "page": 1, | ||
| "pageSize": 10 | ||
| }' | ||
| ``` | ||
|
|
||
| ### Replace documents | ||
|
|
||
| A single or multiple documents can be atomically replaced. | ||
|
|
||
| ```bash | ||
| curl -X 'PUT' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/documents/replace' \ | ||
| -H 'accept: application/json' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "query": { | ||
| "expressions": [ | ||
| { | ||
| "fieldComparisons": [ | ||
| { | ||
| "field": "_id", | ||
| "operator": "EQ", | ||
| "value": "6530f0fa000000000000001f86853b05" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "limit": 1 | ||
| }, | ||
| "document": { | ||
| "first_name": "John", | ||
| "last_name": "Doe", | ||
| "age": 40 | ||
| } | ||
| }' | ||
| ``` | ||
|
|
||
| ### Delete documents | ||
|
|
||
| Documents can be deleted. A document audit preserves document history and allows for retrieval of all revisions, even deleted ones. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/documents/delete' \ | ||
| -H 'accept: application/json' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "query": { | ||
| "expressions": [ | ||
| { | ||
| "fieldComparisons": [ | ||
| { | ||
| "field": "first_name", | ||
| "operator": "EQ", | ||
| "value": "John" | ||
| }, | ||
| { | ||
| "field": "last_name", | ||
| "operator": "EQ", | ||
| "value": "Doe" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "limit": 1 | ||
| } | ||
| }' | ||
| ``` | ||
|
|
||
| ### Audit documents | ||
|
|
||
| Document revisions can be retrieved through a document audit. In auditing, all revisions are tracked and retrievable, even those that have been deleted. | ||
|
|
||
| In order to audit a document, it is necessary to know its unique identifier, which can be obtained by inserting or querying the document. | ||
|
|
||
| ```bash | ||
| curl -X 'POST' \ | ||
| 'http://localhost:8080/api/v2/collection/mycollection/document/6530f0fa000000000000001f86853b05/audit' \ | ||
| -H 'accept: application/json' \ | ||
| -H "sessionID: $sessionid" \ | ||
| -H 'Content-Type: application/json' \ | ||
| -d '{ | ||
| "page": 1, | ||
| "pageSize": 10 | ||
| }' | ||
| ``` | ||
|
|
||
| </WrappedSection> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Data Model | ||
|
|
||
| ::: tip | ||
| By default, Swagger UI is enabled and can be accessed at `http://localhost:8080/api/docs/` | ||
| ::: | ||
|
|
||
| <WrappedSection> | ||
|
|
||
| ### Collection | ||
|
|
||
| A collection is a container for documents of a similar type. Each database can have one or many collections. The documents within a collection can have various structures, but they must all be JSON files. Collections allow you to store and manage related documents together, making it easier to search and retrieve relevant data. | ||
|
|
||
| ### Documents | ||
| Documents are JSON files containing structured data that are stored within a collection. Each document can have multiple versions, allowing you to track changes and maintain a history of modifications. | ||
|
|
||
| </WrappedSection> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.