194 lines
10 KiB
Markdown
194 lines
10 KiB
Markdown
# ETA's Core API (Draft)
|
|
|
|
The following is a draft model for the list of resources the core API exposes:
|
|
|
|
- The list will give an idea of the interaction with the API from the clients perspective.
|
|
|
|
- The list gives an idea of the resources and operations available within the system, to use that information to create the permissions for every resource for every operation.
|
|
|
|
- This list will be translated into user stories in a document shared in a sharepoint for traceability and reproducibility.
|
|
|
|
## API Principles
|
|
|
|
- Applications are the main element of the RBAC system, each application has certain access to the ETA Core resources, like loads, companies directory, among others.
|
|
- Each Application has it's own set of permissions.
|
|
- Each Application has it's own set of roles with permissions associated.
|
|
- Each Application has it's own set of user_sessions.
|
|
- New users shall be created and directly assigned to an application.
|
|
- Any user shall be able to exists in more than one application at the same time.
|
|
- Users may have permissions assigned within an application where it belongs to.
|
|
- Users shall have roles assigned within an application where it belongs to.
|
|
- Users may have apikeys assigned within an application where it belongs to.
|
|
- Users may have sessions assigned within an application where it belongs to.
|
|
- Users may have multiple identities, but only one of each category (phone, email).
|
|
- Only one identity shall be the main user's identity.
|
|
- All resources shall have a list of operations allowed.
|
|
- System shall allow an operation to be perform over a resource only if the permission allows it.
|
|
- No resource is modified without any type of permission validation:
|
|
- User identified by JWT: The JWT is used to retrive the permissions list and use it to validate the authorization.
|
|
- User identified by APIKey: The APIKey is used to retrive the permissions list and use it to validate the authorization.
|
|
|
|
### Identified resources:
|
|
|
|
- **Companies**: A company is represented with a name and description of their operations, it belongs to one of the types: Shipper, Carrier.
|
|
- **Company_Documents**: A company documentation stored in an external BLOB solution, this documentation is part of company register procress.
|
|
- **Vehicles**: A vehicle to transport goods, used by the Carrier company to make a proposal. An employee can be assigned to only one vehicle at a time.
|
|
- **Vehicle_Documents**: Vehicle's documents to legally register it into the system. (Determine if a vehicle requires a registration process).
|
|
- **Locations**: A geographical location important to the company, represents warehouses, either owned warehouses or client's warehouses where the goods need to arraive or be loaded.
|
|
- **Company_Employees**: User's assigned to the company, the employees shall have at most one of the following predefined roles: `admin`, `staff`, `readonly`, `driver`.
|
|
- **Proposals**: A shipment proposal made by the Carrier company, which exposes the public information about the vehicle and the company itself.
|
|
- **Loads**: It represents a publication of load to be transported, created by a Shipper company. A load shall be able to receive many proposals, but only accept one. Accepting a proposal creates the unique `shipment_agreement` resource into the load.
|
|
- **Load_Templates**: It holds common values to help the user quickly create loads on the front-end.
|
|
- **Shipments**: It represents the transport operation of the goods, it is always linked and identified (searched) using the loads identifier.
|
|
|
|
- When a load is published, the load object is modifiable by the Shipper company only. (Created by)
|
|
- When a proposal is sent, the proposal object is modifiable by the Carrier company only. (Created by)
|
|
- When an accepted proposal creates the agreement, the agreement is modified by the Shipper only, the load then exposes the agreement and the rest of the shipment details as part of the view, but in read only mode. For example: Loads.shipment, Loads.shipment_evidences, etc.
|
|
- The Shipment is always associated to a load, when the user cancels the shipment with a Carrier, the shipment is not deleted, but reused for the next agreement.
|
|
- The user that has the role of driver, reads the associated Load, but only modifies the shipment related tables/objects: load_shipment (GPS tracking, and transport state), shipment_evidences.
|
|
|
|
## Proposal of endpoints to expose the resources.
|
|
|
|
Draft of software requirements specification (SRS) to model API endpoints and its responsabilities.
|
|
|
|
- **/meta/applications**:
|
|
- **Operations**:
|
|
- Create application. (idempotency through client UUID)
|
|
- Read applications
|
|
- Update applications
|
|
- Delete applications
|
|
|
|
- **/apps/{app_id}/roles**:
|
|
- **Operations**:
|
|
- Create application roles. (idempotency through client UUID)
|
|
- Read application roles
|
|
- Update application roles
|
|
- Delete application roles
|
|
|
|
- **/apps/{app_id}/permissions**:
|
|
- **Operations**:
|
|
- Create application permissions. (idempotency through client UUID)
|
|
- Read application permissions
|
|
- Update application permissions
|
|
- Delete application permissions
|
|
|
|
- **/apps/{app_id}/users/{user_id}/roles**:
|
|
- **Operations**:
|
|
- Assign roles to user
|
|
- Delete roles from user
|
|
- Read roles from user
|
|
|
|
- **/apps/{app_id}/users/{user_id}/permissions**:
|
|
- **Operations**:
|
|
- Assign permission to user
|
|
- Delete permission to user
|
|
- Read permissions assigned to user
|
|
|
|
- **/apps/{app_id}/users/{user_id}/apikeys**:
|
|
- **Operations**:
|
|
- Create apikeys. (idempotency through client UUID)
|
|
- Read apikeys
|
|
- Delete apikeys
|
|
|
|
- **/apps/{app_id}/auth**:
|
|
- **Operations**:
|
|
- Manage authentication of user:
|
|
- **/app/{app_id}/auth/identity/[phone,email]**:
|
|
- Identify user and return JWT.
|
|
- Create user and assign to application. (idempotency through client UUID)
|
|
- **/app/{app_id}/auth/identity/[phone,email]/verify**:
|
|
- Verify identity and assign to application. (idempotency through client UUID)
|
|
- **/app/{app_id}/auth/logout**:
|
|
- **/app/{app_id}/auth/refresh**:
|
|
- **/app/{app_id}/auth/me**:
|
|
|
|
- **/companies/{company_id}** -> Specific company data or own company updates
|
|
- **/companies/{company_id}/documents**
|
|
- **/companies/{company_id}/vehicles**
|
|
- **/companies/{company_id}/vehicles/{vehicle_id}/documents**
|
|
- **/companies/{company_id}/locations**
|
|
- **/companies/{company_id}/sectors**
|
|
- **/companies/{company_id}/vehicle_types**
|
|
- **/companies/{company_id}/privacy_groups**
|
|
- **/companies/{company_id}/privacy_groups/{group_id}**
|
|
- **/companies/{company_id}/employees** <> Search for users, and add/remove users to the company. Create identities or create users.
|
|
- **/companies/{company_id}/loads** <> Available resources expected on Shippers only
|
|
- **/companies/{company_id}/loads/templates**
|
|
- **/companies/{company_id}/loads/templates/{template_id}**
|
|
- **/companies/{company_id}/loads/{load_id}**
|
|
- **/companies/{company_id}/proposals** <> Available resources expected on Carriers only
|
|
- **/companies/{company_id}/proposals/{proposal_id}**
|
|
|
|
- **/shipments** <> Availble resources for both Shipper and Carrier. (TODO: How to split for writing operations, reading and sharing among companies?)
|
|
- **/shipments/{shipment_id}**
|
|
- **/shipments/{shipment_id}/evidences**
|
|
- **/shipments/{shipment_id}/evidences/{evidence_id}**
|
|
- **/shipments/{shipment_id}/proposal**
|
|
- **/shipments/{shipment_id}/agreement**
|
|
|
|
- **/directories/companies** <> Search for public companies
|
|
- **/directories/loads** <> Search for private companies
|
|
|
|
# Admin Authorization Strategy:
|
|
|
|
The system shall have a predefined system application to control all resources.
|
|
|
|
The system application can't be removed.
|
|
|
|
The system application shall have predefined permissions and roles to control the access to all resources at different granularity levels:
|
|
- CRUD of applications.
|
|
- CRUD of applications' roles.
|
|
- CRUD of applications' permissions.
|
|
- CRUD of applications' users.
|
|
- CRUD of applications' apikeys.
|
|
- etc.
|
|
|
|
The system application shall have an admin user with only apikeys and no identities.
|
|
|
|
The system application's admin user shall have permissions assigned to manage applications.
|
|
|
|
The system application's admin user shall have permissions assigned to manage users.
|
|
|
|
The system application's admin user shall have permissions assigned to manage roles and permissions within applications.
|
|
|
|
The system application's admin user shall have permissions assigned to manage apikeys within applications.
|
|
|
|
The system application's admin user shall not have full control over the system resources.* (No other resource than users, roles, permissions)
|
|
|
|
Every application shall have an admin user with only apikeys and no identities.
|
|
|
|
Every application shall have an admin user to manage application resources.
|
|
|
|
Every application shall have an admin user to manage users within applications:
|
|
|
|
- Shall allow assigning or removing existing users to/from applications.
|
|
- Shall allow create and assign users to applications.
|
|
|
|
The application's admin user shall not have full control over the application resources.* (No other resource than users, roles, permissions)
|
|
|
|
Every application shall have it's own API that serves as an API wrapper to consume system resources.
|
|
|
|
Every application shall have it's own API that serves as an API wrapper to consume application resources.
|
|
|
|
Every application specific API shall use the user's authorization token or apikey to consume application's resources.
|
|
|
|
(Admin Portal shall have it's own API that communicates with the core API to manage system resources associated to the system and the application components).
|
|
|
|
(Admin Portal shall have it's own API key to only create users and assign roles to it).
|
|
|
|
(Admin Portal shall modify system resources by the usage of a JWT of an identified user to enable audit logs of resources manipulation).
|
|
|
|
# Idempotency Strategy:
|
|
|
|
When a resource requires "idempotency", the HTTP header `X-Idempotency-Key` must be provided with an UUID generated from the client.
|
|
|
|
# Authorization Tokens (Core API):
|
|
|
|
When API Key is used, the HTTP header `x-api-key: <apikey>` shall be used.*
|
|
|
|
When JWT is used, the HTTP header `Authorization: Bearer <jwt>` shall be used.
|
|
|
|
When JWT refresh is used, the HTTP header `x-refresh-token: <refresh_token>` shall be used.
|
|
|
|
Every application's specific API (also known as API wrapper) shall use it's own authorization mechanisms.
|