{"id":18400751,"url":"https://github.com/mia-platform/crud-service","last_synced_at":"2026-03-09T17:30:24.263Z","repository":{"id":83962779,"uuid":"594100367","full_name":"mia-platform/crud-service","owner":"mia-platform","description":"A lightweight application to expose restful CRUD API over HTTP interface","archived":false,"fork":false,"pushed_at":"2025-08-06T09:39:59.000Z","size":3802,"stargazers_count":44,"open_issues_count":25,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-06T10:11:40.167Z","etag":null,"topics":["api","crud","mongodb"],"latest_commit_sha":null,"homepage":"https://docs.mia-platform.eu/docs/how_to/crud_service/crud_oss_usage","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mia-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-27T15:48:37.000Z","updated_at":"2025-08-06T09:34:05.000Z","dependencies_parsed_at":"2024-01-09T11:26:22.790Z","dependency_job_id":"73fba18d-7b80-49d9-a073-8408fe6ddbe8","html_url":"https://github.com/mia-platform/crud-service","commit_stats":null,"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/mia-platform/crud-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fcrud-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fcrud-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fcrud-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fcrud-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mia-platform","download_url":"https://codeload.github.com/mia-platform/crud-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fcrud-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270758160,"owners_count":24640192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","crud","mongodb"],"created_at":"2024-11-06T02:36:35.580Z","updated_at":"2026-03-09T17:30:19.236Z","avatar_url":"https://github.com/mia-platform.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003cimg width=\"152\" alt=\"crud-service\" src=\"https://user-images.githubusercontent.com/7142570/218051870-6007d81c-52c2-45e2-bc0b-747d79a5dfec.png\"\u003e\n  \u003ch1\u003eCRUD Service\u003c/h1\u003e\n \n  [![pipeline status][build-svg]][pipeline-link]\n  [![Coverage Status][coverage-svg]][coverage-link]\n  [![license][license-svg]](./LICENSE)\n  [![javascript style guide][standard-mia-svg]][standard-mia]  \n\u003c/div\u003e\n\n## Introduction\n\nThe **CRUD Service** is a lightweight application that exposes an HTTP Interface to perform CRUD operations on MongoDB collections defined via JSON Schema, to make sure to have consistent data in every operation. Moreover, your documents will includes some metadata regarding the creation and the latest update of the document, and a state that will come in handy to better manage draft documents and virtual delete.\n\nThe **CRUD Service** can be launched with [lc39](https://github.com/mia-platform/lc39), that will start a [Fastify](https://fastify.io) instance that will include the functionalities. It also includes a Swagger User Interface to be used to perform any operation for each of the collections defined.\n\nMoreover, the **CRUD Service** can be configured used with the [MongoDB Data Encryption](https://www.mongodb.com/basics/mongodb-encryption) functionality to automatically encrypt data stored in the Database.\n\n## How to run it\n\n### Local deployment\n\nTo deploy the service in your local environment, you must have:\n- Node at version 18 or superior,\n- MongoDB instance at version 4.0 or superior\n\nTo setup Node, we suggest you to install [nvm][nvm] to have multiple node versions in your computer, and use the version suggested in the `.nvmrc` file.\n```sh\nnvm install # \u003c-- to be done only the first time\nnvm use\n```\n\nAbout mongo, we suggest you to have it in a separate Docker container. You can follow this small guide or use the configuration you prefer:\n```shell\ndocker pull mongo:7.0\ndocker volume create mongo\ndocker run --detach --name mongo -p 27017:27017 --mount source=mongo,target=/data/db mongo:7.0\n```\n\nIn case you want to use the MongoDB Encryption functionality, you must install in your machine the [MongoDB Enterprise Server](https://www.mongodb.com/try/download/enterprise?tck=docs_server) and run the `mongocryptd` file (its location may change based on the version you downloaded).\n\nTo run the **CRUD Service**, a `*.env` file including the needed configuration is required. An example of this file is the [default.env](default.env) file. You want to copy the file in a different path to make sure your configuration is ignored by Git (we suggest the name `local.env`):\n```shell\ncp ./default.env ./local.env\n```\n\nThe `default.env` only lists the necessary environment variables to be added to successfully run the CRUD Service in your local machine. A complete list of the environment variables can be found [on the related page](envSchema.js#L25). \n\nOnce you have your _env_ file, you might want to update the `COLLECTION_DEFINITION_FOLDER` and `VIEWS_DEFINITION_FOLDER` environment variables, which represent the folders where the definition of collections and views are found. The CRUD Service accepts _absolute paths_ only, so please verify them. The default values are folders used in unit tests: if you plan to update the files inside for your needs, it's better to use another folder.\n\nWhen everything is ready, you can run the service:\n```shell\nnvm use # \u003c-- only if you use nvm\nnpm i\nnpm run start:local # \u003c-- run the service using the 'local.env' file\n```\n\n### Use the Docker Image\n\nDocker images of the **CRUD Service** are available on [GitHub Registry](https://github.com/orgs/mia-platform/packages/container/package/crud-service) and [DockerHub](https://hub.docker.com/r/miaplatform/crud-service). An image is released in those two registries for every tag created.\n\nIf you instead prefer to create your image (e.g. from your fork), you can use the [`Dockerfile`](./Dockerfile) to generate your image:\n\n```shell\ndocker build -t crud-service .\n```\n\nThanks to the support of [Docker BuildKit](https://docs.docker.com/build/buildkit/), you can also decide to create an image of the CRUD Service without including the `mongocryptd` libraries:\n\n```shell\nDOCKER_BUILDKIT=1 docker build -t crud-service-no-encryption --target=crud-service-no-encryption .\n```\n\nIf you are interested in it, you can get one and run it locally with these commands:\n\n```shell\ndocker run --name crud-service \\\n           --detach \\\n           --env LOG_LEVEL=info \\\n           --env MONGODB_URL=mongodb://\u003cyour-mongo-container-ip\u003e/\u003cdatabase-name\u003e \\\n           --env COLLECTION_DEFINITION_FOLDER=/home/node/app/collections \\\n           --env USER_ID_HEADER_KEY=userid \\\n           --env CRUD_LIMIT_CONSTRAINT_ENABLED=true \\\n           --env CRUD_MAX_LIMIT=200 \\\n           --mount type=bind,source=$(pwd)/tests/collectionDefinitions,target=/home/node/app/collections \\\n           --publish 3000:3000 \\\n           \u003cyour-crud-service-image-name\u003e:latest\n```\n\nPlease note that you can mount the `.env` file with your CRUD Service configuration instead of manually including the environment variables in the command.\n\n### How to use it\n\nYou can access the **Swagger User Interface**, generally available at `http://localhost:3000/documentation` (it depends on which port you deployed the service). From there you can verify the list of Collections and Views defined and execute HTTP requests to effectively use the service.\n\n## Local development\n\n### (CSFLE)[https://www.mongodb.com/docs/manual/core/csfle/] Support\n\nIn order to run the service with the Client-Side Field Level Encryption feature enable it is necessary to download from (MongoDB Download Center)[https://www.mongodb.com/try/download/enterprise] the `crypt_shared` dynamic library, which provides the automatic encryption functionalities. Upon the compressed file is downloaded, please uncompress and copy the file `lib/mongo_crypt_v1.so` into the folder `.local/lib` within this repository.\nIn case you would like to choose a different location for storing the `crypt_shared` library, please remember to customize the `CRYPT_SHARED_LIB_PATH` environment variable before launching the service locally or running tests.\n\n:::note\nPlease remember that CSFLE is a MongoDB Atlas/Enterprise exclusive feature. Consequently, please ensure you are subscribed to one of such plans before using it.\n:::\n\n### Run tests\n\nWe use [tap](https://github.com/tapjs/node-tap) to test the **CRUD Service**. Once you have all the dependency in place, you can simply launch it with:\n\n```shell\nnpm run coverage\n```\n\nIt will run the tests with the coverage report that you can view as an HTML page in `coverage/lcov-report/index.html`. \n\nTo run only one test:\n\n```shell\nenv MONGO_VERSION=7.0 MONGO_HOST=127.0.0.1 TAP_BAIL=1 node tests/createIndexes.test.js\n```\n\n## Architecture\n\n```\n+----------------------+  +----------------------+  +----------------------+  +----------------------+\n|                      |  |                      |  |                      |  |                      |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |                      |\n|   |             |    |  |   |             |    |  |   |             |    |  |    +-------------+   |\n|   | CrudService |    |  |   | CrudService |    |  |   | CrudService |    |  |    |             |   |\n|   |             |    |  |   |             |    |  |   |             |    |  |    | JoinService |   |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |    |             |   |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |    +-------------+   |\n|   |             |    |  |   |             |    |  |   |             |    |  |                      |\n|   | QueryParser |    |  |   | QueryParser |    |  |   | QueryParser |    |  |                      |\n|   |             |    |  |   |             |    |  |   |             |    |  |                      |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |                      |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |                      |\n|   |             |    |  |   |             |    |  |   |             |    |  |                      |\n|   |HTTPInterface|    |  |   |HTTPInterface|    |  |   |HTTPInterface|    |  |                      |\n|   |             |    |  |   |             |    |  |   |             |    |  |                      |\n|   +-------------+    |  |   +-------------+    |  |   +-------------+    |  |                      |\n|                      |  |                      |  |                      |  |                      |\n| Crud on a collection |  | Crud on a collection |  | Crud on a collection |  |      JoinPlugin      |\n|                      |  |                      |  |                      |  |                      |\n+-----------^----------+  +-----------^----------+  +-----------^----------+  +-----------^----------+\n            |                         |                         |                         |\n+-----------+-------------------------+-------------------------+-------------------------+----------+\n|                                                                                                    |\n|             +--------------------+                               +--------------------+            |\n|             |                    |                               |                    |            |\n|             | Model definitions  |           FASTIFY             | Mongodb connection |            |\n|             |                    |                               |                    |            |\n|             +--------------------+                               +--------------------+            |\n|                                                                                                    |\n+----------------------------------------------------------------------------------------------------+\n```\n\nThe CRUD Service application uses Fastify to connect to a MongoDB instance (thanks to the @fastify/mongodb plugin) and execute CRUD operations. At startup, it requires several details, such as the MongoDB URL to communicate with, but also the folders where the definitions of the collections and the views can be found. A complete and comprehensive list of the environment variables needed can be found on the [Configuration page](./docs/20_Configuration.md).\n\nThe collections and the views available in the service are the ones with Model definitions stored in the folders defined in, respectively, `COLLECTION_DEFINITION_FOLDER` and `VIEWS_DEFINITION_FOLDER`. In each folder, there will be one file per collection/view. Each file should be a JSON or a javascript file.\n\nThese models will be analyzed by the [JSONSchemaGenerator](./lib/JSONSchemaGenerator.js) class to be transformed to a JSON Schema that will be used to validate HTTP requests, to serialize the output and to return these information to the user as a documentation. \n\nThe service exposes several APIs to communicate with the collections. You can send requests as you prefer: you can use curl, use an application such as PostMan, or use the integrated Swagger API Interface accessible to `http://{{url}}/documentation`.\n\nWhen the Service is live, every HTTP request executed will be caught by the HTTP Interface that works as a communication channel with the CRUD Service. The data included with the request (query parameters, body, commands) is evaluated by the [`QueryParser`](./lib/QueryParser.js) class to verify the query to make sure that every value associated to a specific field is in the correct type. Then it's forwarded to the [`CrudService`](./lib/CrudService.js) class to execute the query. Result of `GET` requests are passed to the [`AdditionalCaster`](./lib/AdditionalCaster.js) class to casts GeoPoints and ObjectIds properties in the data.\n\n### Define your collections\n\n#### JSONSchema Configuration\n\nThe collections should be included in separate JSON or JavaScript files in the folder defined with the environment variable `COLLECTION_DEFINITION_FOLDER`. Each collection object requires the following fields:\n\n| Name | Type | Required | Default value | Description |\n|------|------|----------|---------------|-------------|\n| id | String | - | - | Additional identifier that can be associated to the collection definition. |\n| endpointBasePath | String | \u0026check; | - | The endpoint path, used as entry point to CRUD operations |\n| name | String | \u0026check; | - | The name of the collection on MongoDB. |\n| defaultState | String | - | `DRAFT` | The default state assigned to a document when inserted. Can be one of the [\\_\\_STATE__ available values](#metadata-fields) |\n| defaultSorting | Object | - | - |  [MongoDB document](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/#ascending-descending-sort) defining the default order applied to the result set during find operations, **only if no explicit sorting is defined**. A complete description of the field can be found [in the section of the collection JSON Schema](./lib/model.jsonschema.js#L487). |\n| schema | JSONSchemaStandard | \u0026check; | - | The JSON Schema configuration of the fields to be included in the collection object. A complete description of its fields can be found in the [ _schema_](./lib/model.jsonschema.js#L495)  section of the collection JSON Schema. |\n| indexes | Array of objects | \u0026check; | - | The list of indexes to be created when starting the service and initializing all the collections. A complete description of its fields can be found [in the _indexes_ section of the collection JSON Schema](./lib/model.jsonschema.js#L692) |\n| tags | Array of strings | - | [] | The list of tags to be associated to the collection's endpoints, useful to group different endpoint under the same section inside the swagger. |\n\n\u003e **WARNING:** The definition of _unique_ indexes makes the CRUD Service fail at startup if the database contains inconsistent documents (e.g. documents that have the same value for that key). Also documents without that key are all considered to have the same value (_null_), thus [violating the uniqueness](https://docs.mongodb.com/manual/core/index-unique/#unique-index-and-missing-field), and causing the index generation (and the CRUD Service) to fail at startup.\n\n\u003e **WARNING:** every index that is not specified in the collection definition wil be **dropped** at startup of the application, unless its _name_ starts with the `preserve_` prefix.\n\n\u003e **TIP:** if a default sorting is defined, is suggested to have its fields covered by an index. \n\nSeveral examples of collections can be found in the [Collections Definitions folder](./tests/newCollectionDefinitions/),\nwhereas the schema that defines and validate the data model definition can be found [here](./lib/model.jsonschema.js).\n\n#### Custom Fields configuration (deprecated)\n\nThe collections should be included in separate JSON or JavaScript files in the folder defined with the environment variable `COLLECTION_DEFINITION_FOLDER`. Each collection object requires the following fields:\n\n| Name | Type | Required | Default value | Description |\n|------|------|----------|---------------|-------------|\n| id | String | - | - | Additional identifier that can be associated to the collection definition. |\n| endpointBasePath | String | \u0026check; | - | The endpoint path, used as entry point to CRUD operations |\n| name | String | \u0026check; | - | The name of the collection on MongoDB. |\n| defaultState | String | - | `DRAFT` | The default state assigned to a document when inserted. Can be one of the [\\_\\_STATE__ available values](#metadata-fields) |\n| defaultSorting | Object | - | - |  [MongoDB document](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/#ascending-descending-sort) defining the default order applied to the result set during find operations, **only if no explicit sorting is defined**. A complete description of the field can be found [in the section of the collection JSON Schema](./lib/model.jsonschema.js#L76). |\n| fields | Array of objects | \u0026check; | - | The list of fields to be included in the collection object. A complete description of its fields can be found [in the _fields_ section of the collection JSON Schema](./lib/model.jsonschema.js#L84). |\n| indexes | Array of objects | \u0026check; | - | The list of indexes to be created when starting the service and initializing all the collections. A complete description of its fields can be found [in the _indexes_ section of the collection JSON Schema](./lib/model.jsonschema.js#L247) |\n| tags | Array of strings | - | [] | The list of tags to be associated to the collection's endpoints, useful to group different endpoint under the same section inside the swagger. |\n\n\u003e **WARNING:** The definition of _unique_ indexes makes the CRUD Service fail at startup if the database contains inconsistent documents (e.g. documents that have the same value for that key). Also documents without that key are all considered to have the same value (_null_), thus [violating the uniqueness](https://docs.mongodb.com/manual/core/index-unique/#unique-index-and-missing-field), and causing the index generation (and the CRUD Service) to fail at startup.\n\n\u003e **WARNING:** every index that is not specified in the collection definition wil be **dropped** at startup of the application, unless its _name_ starts with the `preserve_` prefix.\n\n\u003e **TIP:** if a default sorting is defined, is suggested to have its fields covered by an index. \n\nSeveral examples of collections can be found in the [Collections Definitions folder](./tests/collectionDefinitions/),\nwhereas the schema that defines and validate the data model definition can be found [here](./lib/model.jsonschema.js).\n\n### Define your views\n\nThe MongoDB Views should be included in separate JSON or JavaScript files in the folder defined with the environment variable `VIEWS_DEFINITION_FOLDER`. Each collection object requires the following fields:\n\n| Name | Type   | Required | Default value | Description |\n|------|--------|----------|---------------|-------------|\n| name | String | \u0026check; | - | The name of the view, used as identifier |\n| source | String | \u0026check; | - | The name of the collection to be used as source to generate the view |\n| type | `view` | \u0026check; | - | The type of MongoDB element, which is required by CRUD Service to understand which operations might be performed. It should be the value `view`. |\n| pipeline | Object | \u0026check; | - | The pipeline to aggregate the MongoDB View. It uses the same syntax of the [Aggregation Pipeline](https://www.mongodb.com/docs/manual/core/aggregation-pipeline/) |\n\nSeveral examples of collections can be found in the [Views Definitions folder](./tests/viewsDefinitions/),\nwhereas the schema that defines and validate the data model definition can be found [here](./lib/model.jsonschema.js) (it is the same schema of the collection definition).\n\n**Note:** `__STATE__` field **must** be returned in each record eventually produced by the view aggregation pipeline.\nOn the contrary, records without the `__STATE__` field would always be filtered out by the CRUD Service operations\n(e.g. listing records via `GET /\u003ccollection-name\u003e` API method would not consider them in the result set).\n\n### Writable views\n\nThe CRUD service offers the functionality to modify a view by editing the underlying collection. This enables clients to interact with a view as if it was an independent collection. Additionally, the service will expose additional routes that provide a comprehensive list of all possible values that can be included as lookup values, if any in the view.\n\nTo enable this feature, you need to include the `enableLookup: true` property in the view configuration JSON. By default, this setting is set to false.\n\nFor more information on correctly configuring and understanding the capabilities of writable views, please refer to the [writable views documentation](./docs/50_Writable_Views.md).\n\n### Headers\n\nEvery HTTP request trusts in some headers:\n\n* **acl_rows** allows us to limit the rows that the requester can see. The query to limit the rows is passed a stringified json.\n* **acl_read_columns** allows us to limit the properties to be returned to the requester. The list of properties is passed as a stringified json.\n* **json-query-params-encoding** allows us to use a different encoder for the data passed as query parameters (only supported value: _base64_)\n* **user_id** includes the identifier of the user executing the request\n\n### Metadata fields\n\nWhen working with collections via CRUD Service, some fields will be automatically generated and updated. Those fields are the following:\n\n* **updaterId** is the user id (string) that requests the last change successfully\n* **updatedAt** is the date (date) of the request that has performed the last change\n* **creatorId** is the user id (string) that creates this object\n* **createdAt** is the date (date) of the request that has performed the object creation\n* **\\_\\_STATE__** is the current state of the document, can be one of the following four:\n  * `PUBLIC` (by default, only data in `public` will be shown via `GET` requests)\n  * `DRAFT`\n  * `TRASH` (a \"soft delete\" state, ideally to be visible in the Trash Bin of a backoffice application)\n  * `DELETED` (marked as delete, it shouldn't be shown in GET requests and it shouldn't be modified with PUT operations)\n\n#### Document State management\n\nWe've just explained the difference between the four possible states of a document. This property can be set directly during an _insert_, and can be changed via REST API calls only in the case of the following transformations:\n- a document in `PUBLIC` can be moved to `DRAFT` or `TRASH`; \n- a document in `DRAFT` can be moved to `PUBLIC` or `TRASH`; \n- a document in `TRASH` can be moved to `DRAFT` or `DELETED`; \n- a document in `DELETED` can be moved only to `TRASH`;\nAny request to transition to a not allowed state will be refused and a _400 Bad Request_ will be returned.\n\n**NOTE**: If you request to update the state to its current value (e.g., from `PUBLIC` to `PUBLIC`), it will be successful. The `__STATE__` will remain the same, but the _updaterId_ and _updatedAt_ metadata fields will be updated.\n\nOperations of hard delete are supported, although the permissions over this type of operation are defined via ACL.\n  \n### Crud service\n\nThis class makes the query to the mongodb collection, manages `updaterId`, `updatedAt`,\n`creatorId`, `createdAt`, `__STATE__` and checks whether operations are allowed.\n\n### QueryParser\n\nThis class casts the value from the query, the body and the commands in order to insert `Date` and `ObjectId`\nand perform other conversions such as `GeoPoint` where needed\n\n### AdditionalCaster\n\nThis class casts the value of the result from a query executed in order to have consistent data with the definition of the collection. It operates only on one type of properties: MongoDB's `GeoPoint`.\n\n### HTTPInterface\n\nThis piece of code is a communication channel between HTTP and the CrudService.\nIt uses the `QueryParser` to cast the value before forwarding the request to the `crudService`, and the `AdditionalCaster` to cast the GeoPoints and ObjectIds values inside the response to be returned.\n\nThe HTTPInterface includes by default different API methods for every kind of operation. The following are available for both Collections and Views:\n\n| Verb | API Method                   | Description                                      | \n|------|------------------------------|--------------------------------------------------|\n| GET  | {base URL}/{endpoint}/       | Returns a list of documents.                     |\n| GET  | {base URL}/{endpoint}/export | Export the collection in different file formats. |\n| GET  | {base URL}/{endpoint}/{id}   | Returns the item with specific _ID_.             |\n| GET  | {base URL}/{endpoint}/count  | Returns the number of items in the collection.   |\n\nFor collections, also the following methods are available:\n\n| Verb   | Method                           | Description                                                                                         | \n|--------|----------------------------------|-----------------------------------------------------------------------------------------------------|\n| POST   | {base URL}/{endpoint}/           | Add a new item to the collection.                                                                   |\n| POST   | {base URL}/{endpoint}/upsert-one | Update an item in the collection. If the item is not in the collection, it will be inserted.        |\n| POST   | {base URL}/{endpoint}/bulk       | Insert new items in the collection.                                                                 |\n| POST   | {base URL}/{endpoint}/state      | Change state of multiple items of the collection.                                                   |\n| POST   | {base URL}/{endpoint}/{id}/state | Change state of the item with specific _ID_.                                                        |\n| POST   | {base URL}/{endpoint}/validate   | Verify if the body of the request is valid for an insertion in the collection.                      |\n| POST   | {base URL}/{endpoint}/import     | Inserts new items in the collection from file (json, ndjson and csv).                               |\n| PATCH  | {base URL}/{endpoint}/           | Update the items of the collection that match the query.                                            |\n| PATCH  | {base URL}/{endpoint}/{id}       | Update the item with specific _ID_ in the collection.                                               |\n| PATCH  | {base URL}/{endpoint}/bulk       | Update multiple items of the collection, each one with its own modifications                        |\n| PATCH  | {base URL}/{endpoint}/import     | Update the items in the collection from file (json, ndjson and csv), it must include the _ID_ field |\n| DELETE | {base URL}/{endpoint}/           | Delete multiple items from the collection.                                                          |\n| DELETE | {base URL}/{endpoint}/{id}       | Delete an item with specific _ID_ from the collection.                                              |\n\nAll these methods might include additional query parameters to refine the search. To have more detail, you can check the [live documentation](http://localhost:3000/documentation) (available only when a service instance is started locally) or refer to the service [documentation overview](./docs/10_Overview_and_Usage.md#crud-endpoints).\n\n\n### JoinService\n\nThe CRUD Service includes also the `join` feature, to join two different models. That feature is served on `/join/\u003ctype\u003e/:from/:to/export`, where:\n- type: `one-to-one` or `one-to-many` or `many-to-many`\n- from: the collection endpoint from which the join starts\n- to: the collection endpoint which the join ends to\nThis API responses always in `application/application/x-ndjson`\n\nSee the documentation to see which parameters are available.\n\n## Performance test\n\nWe use [k6](https://example.com/k6) to simulate the load of traffic directed to the CRUD Service and retrieve some performance metrics. At every version released, a workflow automatically starts executing the following tests:\n\n- **Load Test**: 10 virtual users execute POST requests for one minute on the same collection, then 100 virtual users execute GET, PATCH, and DELETE requests for another minute on the data created.\n- **Spike Test**: We simulate a spike of activity by increasing the number of users from 5 to 500 in 30 seconds, then a decrement of activity from 500 to 5 in another 30 seconds. During this test, only GET requests are executed on a collection that includes 100,000 documents.\n- **Stress Test**: We simulate a brief time of intense activity with 250 users for 90 seconds, followed by a decrement of activity to 5 in 30 seconds. During this test, only GET requests are executed on a collection that includes 100,000 documents.\n\nThese tests are executed ahead of every version release to ensure that further updates do not cause a degradation of performance that might affect the usage of the CRUD Service.\n\n### Execute Performance Test on a Local Environment\n\nIn case you want to run the tests on your local environment, follow these steps:\n\n- Start the CRUD Service in a Docker container.\n- Have a MongoDB instance ready for use, eventually loaded with existing documents to simulate tests.\n\nTo simplify these operations, you can use the same setup for the tests executed during the GitHub workflow, by starting an instance of the CRUD Service using collections and views included in the folder `_bench/definitions`. Use the script `bench/utils/generate-customer-data.js` to quickly include mock documents in the _customers_ collection.\n\nThe `generate-customer-data.js` script can be executed at any time with the following command:\n\n```bash\nnode bench/utils/generate-customer-data.js -c \u003cconnection string\u003e -d \u003cdatabase name\u003e -n \u003cnumber of documents\u003e -s \u003cnumber of total shops\u003e\n```\nWhere the script arguments are the following:\n- **connection string** (default: _mongodb://localhost:27017_): Connects to your MongoDB instance.\n- **database name** (default: _bench-test_): Specifies the name of the database to write to.\n- **number of documents** (default: _100000_): Sets the number of documents to be created and saved in the customers collection of the specified database.\n- **number of total shops** (default: _250_): Defines a random value (from 1 to the specified number) applied to the shopID field of each document to be saved.\n\n\nTo simplify these operations, you can execute the command `npm run bench:init` from your shell. This command starts a container with a MongoDB 6.0 instance, a container with the CRUD Service (built from your current branch), and populates the _customers_ collection with 100,000 documents.\n\nTo execute any test, start the k6 service with the following command:\n\n```bash\ndocker compose -f bench/dc-k6.yml up \u003cservice name\u003e\n```\n\nRemember to replace `\u003cservice name\u003e` with one of the following:\n| Service Name                   | Description                                                                                     | File name containing the test            | \n|--------------------------------|-------------------------------------------------------------------------------------------------|------------------------------------------|\n| k6-load-test                   | Executes a Load Test (1 minute of POST, 1 minute of GET/PATCH/DELETE) on the _items_ collection | [load-test.js](bench/scripts/load-test.js)         |\n| k6-smoke-test                  | Executes a Smoke Test (1 minute of GET requests) on the _customers_ collection                  | [smoke-test.js](bench/scripts/smoke-test.js)         |\n| k6-stress-test-on-collections  | Executes a Stress Test (GET requests for 90 seconds by 250 users) on the _customers_ collection | [stress-test-on-collections.js](bench/scripts/stress-test-on-collections.js)         |\n| k6-stress-test-on-view         | Executes a Stress Test (GET requests for 90 seconds by 250 users) on the _registered-customers_ view | [stress-test-on-view.js](bench/scripts/stress-test-on-view.js)         |\n| k6-spike-test                  | Executes a Spike Test (simulate a spike of 500 concurrent users for GET requests) on the _customers_ collection | [spike-test.js](bench/scripts/spike-test.js)         |\n| k6-bulk-test                  | Executes a Bulk Test (simulate a spike of 40 `POST /bulk` requests and 40 `PATCH /bulk` requests of 10k records each) on the _items_ collection | [bulk-test.js](bench/scripts/bulk-test.js)         |\n| runner                         | An empty test that can be populated for tests on local environment | [runner.js](bench/scripts/runner.js)         |\n\nWe suggest you use the runner to execute customized tests for your research.\n\nAlso, do not run all the tests alltogether via `docker compose -f bench/dc-k6.yml up`, without specifying a test name, otherwise all the tests will run at the same time and the results will not be specific to any test but a global indication on how to service worked during the execution of **all** the tests.\n\nYou are free to modify and improve those tests and the definitions used for them but please remember to not use any sensible data.\n\n## FAQ\n\n### How do I change the Mongocryptd version on Debian\n\nTo change the cryptd version, you can download the binary file from the [MongoDB Repositories][cryptd], then navigate to the following subpath: `{version_wanted}/main/binary_amd64/mongodb-enterprise-cryptd_{version_wanted}_amd64.deb`.\n\nFor example, for version 5.0.14, the final url of the `.deb` will be: https://repo.mongodb.com/apt/debian/dists/bullseye/mongodb-enterprise/5.0/main/binary-amd64/mongodb-enterprise-cryptd_5.0.14_amd64.deb\n\n## Client-side Libraries\n\nFor leveraging the CRUD Service APIs in your services you can use one of the following libraries based on supported languages\n\n - [Golang](https://github.com/mia-platform/go-crud-service-client)\n\n## Contributing\n\nCRUD Service is an active project developed and maintained by [Mia Platform](https://mia-platform.eu/), it is distributed open source and it is [Apache 2 licensed](./LICENSE).\nYou're more than welcome to partecipate by creating and/or partecipating to public discussion and actively partecipate to the development of the application.\n\nThe two main communication channel are:\n- in the [issues tab](https://github.com/mia-platform/crud-service/issues);\n- in the [official Mia Platform Community Discussion page](https://github.com/mia-platform/community/discussions?discussions_q=label%3A%22CRUD+Service%22) (if you want to create a discussion here, please add the _CRUD Service_ tag);\n\nPlease read [CONTRIBUTING.md](./CONTRIBUTING.md) for further details about the process for submitting pull requests.\n\n## Disclaimer\n\n### Usage of MongoDB Data Encryption\n\nThe CRUD Service can be used along with the [MongoDB Data Encryption](https://www.mongodb.com/basics/mongodb-encryption) functionality, and the images available includes the libraries to use this feature.\n\nHowever, the MongoDB Data Encryption should be used along with [MongoDB Atlas](https://www.mongodb.com/atlas/database) or [MongoDB Enterprise Advanced](https://www.mongodb.com/products/mongodb-enterprise-advanced). When you use the CRUD Service, for personal projects or commercial applications, you should be aware of that and you will have to comply with [MongoDB terms of use](https://www.mongodb.com/legal/terms-of-use) accordingly.\n\nMia Platform s.r.l. does not respond to any improper use of the MongoDB Data Encryption or any other MongoDB product.\n\n[nvm]: https://github.com/creationix/nvm\n[cryptd]: https://repo.mongodb.com/apt/debian/dists/bullseye/mongodb-enterprise/\n\n[pipeline-link]: https://github.com/mia-platform/crud-service/actions\n[build-svg]: https://img.shields.io/github/actions/workflow/status/mia-platform/crud-service/main.yml\n[license-svg]: https://img.shields.io/github/license/mia-platform/CRUD-service\n\n[coverage-svg]: https://coveralls.io/repos/github/mia-platform/crud-service/badge.svg?branch=main\n[coverage-link]: https://coveralls.io/github/mia-platform/crud-service?branch=main\n[standard-mia-svg]: https://img.shields.io/badge/code_style-standard--mia-orange.svg\n[standard-mia]: https://github.com/mia-platform/eslint-config-mia\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmia-platform%2Fcrud-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmia-platform%2Fcrud-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmia-platform%2Fcrud-service/lists"}