GoETAAPI/docs/software_requirements_specification.md

ETA's Core API

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:

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.