{"id":9991,"library":"nsj-rest-lib","title":"NSJ Rest Lib","description":"nsj-rest-lib is a Python library for building declarative REST APIs, adhering to internal guidelines and focusing on DTO (Data Transfer Object) and Entity patterns. It simplifies API creation by abstracting common patterns for data mapping, validation, and persistence. The current version is 6.4.1, and it maintains an active release cadence with regular feature additions and bug fixes.","status":"active","version":"6.4.1","language":"en","source_language":"en","source_url":"https://github.com/Nasajon/nsj_rest_lib","tags":["REST API","DTO","ORM","framework","declarative","API development"],"install":[{"cmd":"pip install nsj-rest-lib","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"DTOBase","correct":"from nsj_rest_lib.dto.dto_base import DTOBase"},{"symbol":"DTOField","correct":"from nsj_rest_lib.dto.fields import DTOField"},{"symbol":"DTOAggregator","correct":"from nsj_rest_lib.dto.fields import DTOAggregator"},{"symbol":"DTOSQLJoinField","correct":"from nsj_rest_lib.dto.fields import DTOSQLJoinField"},{"symbol":"EntityBase","correct":"from nsj_rest_lib.entity.entity_base import EntityBase"},{"symbol":"ServiceBase","correct":"from nsj_rest_lib.service.service_base import ServiceBase"}],"quickstart":{"code":"from dataclasses import dataclass\nfrom nsj_rest_lib.dto.dto_base import DTOBase\nfrom nsj_rest_lib.dto.fields import DTOField, DTOAggregator\nfrom nsj_rest_lib.entity.entity_base import EntityBase\n\n# 1. Define your Entity (maps to a database table)\n@dataclass\nclass ProductEntity(EntityBase):\n    id: int\n    name: str\n    description: str\n    price: float\n\n# 2. Define your DTO (Data Transfer Object, maps to API representation)\nclass ProductDTO(DTOBase):\n    id: int = DTOField(pk=True)\n    name: str = DTOField()\n    price: float = DTOField(decimal_places=2)\n\n# 3. Example of an aggregated DTO using DTOAggregator (v4.9.0+)\nclass ProductDetailsDTO(DTOBase):\n    category: str = DTOField()\n    weight_kg: float = DTOField()\n\nclass FullProductDTO(DTOBase):\n    id: int = DTOField(pk=True)\n    name: str = DTOField()\n    description: str = DTOField()\n    details: ProductDetailsDTO = DTOAggregator()\n\nprint(\"DTOs and Entities defined successfully.\")\nprint(f\"ProductDTO fields: {ProductDTO.get_fields()}\")\nprint(f\"FullProductDTO fields: {FullProductDTO.get_fields()}\")\n","lang":"python","description":"This quickstart demonstrates how to define an Entity (mapping to a database table) and various DTOs (Data Transfer Objects) for API representation, including using `DTOAggregator` for nested structures that map to a single underlying entity. This setup forms the core declarative definition for building REST APIs with nsj-rest-lib."},"warnings":[{"fix":"Review your update operations and DTO definitions. Ensure all fields you intend to update are present in the `DTO`. If a field is not in the DTO, it will no longer be implicitly updated or set to `NULL` by the library.","message":"Update queries behavior changed in v4.0.0. Previously, all fields in an `Entity` were considered for an `UPDATE` SQL statement, potentially setting non-DTO fields to `NULL`. Now, only fields explicitly defined in the `DTO` being used for the update are included.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"When using `DTOAggregator`, ensure your database schema and entity mapping reflect that the nested DTO's properties are columns within the same primary entity table, not a separate joined entity. Plan your `Entity` definitions accordingly.","message":"The `DTOAggregator` (introduced in v4.9.0) allows nesting DTOs in the JSON representation, but the underlying data for both the parent and aggregated DTO fields are expected to come from a single, flat entity/table in the database.","severity":"gotcha","affected_versions":">=4.9.0"},{"fix":"To ensure the complete (summary) object is echoed back after an `INSERT`, set the `retrieve_after_insert=True` flag in your route or service configuration for POST requests.","message":"After a `POST` operation, the default behavior (before v3.0.0 and if not explicitly configured) might not return the complete created object in the response. This can lead to front-end issues expecting a full object echo.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"If you encounter errors about a field being read-only, either remove `read_only=True` from the `DTOField` definition if it should be writable, or ensure your API clients do not send data for that specific field during write operations.","message":"Using `read_only=True` on a `DTOField` (introduced in v2.8.0) will prevent that field from being writable during `POST`, `PUT`, or `PATCH` operations, even if it's included in the request payload.","severity":"gotcha","affected_versions":">=2.8.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Verify that all fields intended for update are explicitly defined in the DTO used for the update operation. Ensure DTOs are kept up-to-date with entity definitions, reflecting the v4.0.0 breaking change.","cause":"Attempting to update an entity field that is not explicitly defined in the DTO used for the update, or using an outdated DTO definition, especially after upgrading to v4.0.0.","error":"KeyError: 'some_field_name' or ValueError: 'some_field_name' is not a valid field for this DTO/Entity"},{"fix":"Ensure `retrieve_after_insert=True` is set on your route or service configuration for POST requests if your client expects the full object (with its ID and other properties) to be returned after an insert (available in v3.0.0+).","cause":"The default POST response might not return the full created object, especially before v3.0.0 or if `retrieve_after_insert` is not explicitly enabled, leading to client-side errors when trying to access properties.","error":"AttributeError: 'NoneType' object has no attribute 'id' (or other field) in POST response handling."},{"fix":"Either remove the `read_only=True` flag from the `DTOField` definition if the field should be modifiable, or ensure that your API requests for `POST`, `PUT`, or `PATCH` do not include data for this specific field.","cause":"You are attempting to write data to a DTOField that has been explicitly marked with `read_only=True`.","error":"nsj_rest_lib.exceptions.FieldNotWritableException: Field 'my_read_only_field' is read-only."},{"fix":"Always create a new class that inherits from `EntityBase` or `DTOBase` and define its fields. For example, `class MyConcreteEntity(EntityBase): ...` or `class MyConcreteDTO(DTOBase): ...`.","cause":"You are trying to directly instantiate an abstract base class like `EntityBase` or `DTOBase` instead of defining a concrete subclass that inherits from it.","error":"TypeError: can't instantiate abstract class EntityBase with abstract methods __annotations__ (or similar for DTOBase)"}]}