Name:
URL Contexts
Status:
approved
Created:
2024-08-22
Updated:
2024-08-22
URL Contexts (#3103)
Definitions
-
Organization Context: The context in which data is accessed within the organization.
-
User Context: The context in which data is accessed by the authenticated user.
-
/me: The URL path moniker to denote the endpoint will retrieve data specific to the authenticated user.
Guidelines for Endpoint Design
-
Organization Contexts: All endpoints should, at a minimum, be scoped to the current organization, determined by
the OrgID claim in the JWT.
-
User Contexts: Endpoints may choose to scope data to the authenticated user. This should be done for endpoint
only when the data is inherently personal and directly related to the authenticated user. This helps to avoid ambiguity
and ensures clarity regarding what data is being retrieved.
-
Clarity in Context: Ensure that the endpoint’s path clearly conveys the context of the data being retrieved.
Ensure that all organization context endpoints should be either singletons or expect a resource ID in the URL path
(e.g. /v3/users/{userId}). Ensure that all user context endpoints should use me in lieu of the resource ID (e.g.
/v3/users/me).
Example Endpoints
Organization Context
/v3/users/{userId} - Retrieve information about a specific user within the current organization./v2/organizations/{organizationId} - Retrieve information about a specific organization./v1/notifications - Retrieve notifications specific to the current organization./v1/notifications/{notificationId} - Retrieve information about a specific notification.
User Context
/v3/users/me - Retrieve information about the authenticated user within the current organization./v2/organizations/me - Retrieve information about the authenticated user's organization./v1/notifications/me - Retrieve notifications specific to the authenticated user.