Initial contract for the authorizations endpoints

authorizations.md

@@ -0,0 +1,93 @@
+# Authorizations Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+An authorizations is the representation of some rights that are available to a specific user (eperson) on a defined object, eventually the whole repository (site object).
+All the authorizations are always explicitly listed regardless to how they are grant, by direct policies via groups' membership or open to everyone (anonymous users).
+Please note that these endpoints are all READ-ONLY, authorizations are granted and withdrawn as result of business processes, configurations and resource policies.
+
+## Main Endpoint
+**/api/authz/authorizations**
+
+As we don't have yet an use case to iterate over all the existent authorizations the main endpoint is not implemented and a 405 error code is returned according to our [general error response codes](README.md#Error-codes).
+
+## Single Authorization
+**/api/authz/authorizations/<:id>**
+
+Provide detailed information about a specific authorization. The JSON response document is as follow
+
+```json
+{
+  "id": [eperson-uuid_]feature-id_object-type_object-id,
+  "type": "authorization"
+}
+```
+
+Attributes
+* id: the id of the authorization resource is defined by the combination of the eperson uuid (if not null), the feature id and the object type and (uu)id joined with an underscore 
+
+Exposed links:
+* eperson: link to the eperson that the authorization belong to. Can be null for authorizations grant to unlogged users
+* feature: link to the feature enabled by this authorization
+* object: link to the object where this authorization apply. Not limited to DSpace objects, see the controlled list defined for the type attribute in the [features endpoint](features.md#resourcetype) for more details
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated and the policy is not related to the ANONYMOUS user (eperson null)
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators and the user mentioned in the authorization can access
+* 404 Not found - if the authorization doesn't exist (or was already deleted)
+
+### Search methods
+#### object
+**/api/authz/authorizations/search/object?uri=<:uri>[&eperson=<:uuid>&feature=<:string>]**
+
+The supported parameters are:
+* page, size [see pagination](README.md#Pagination)
+* uri: mandatory, the object to use for the authorization check. The full URI of the rest resource must be specified, i.e. https://{dspace.url}/api/core/community/{uuid}
+* eperson: optional, the uuid of the eperson to evaluate for authorization. If not specified authorization of anonymous users will be returned
+* feature: optional, limit the returned authorization to the specified feature (this provide an alternative to codify the authorization id rule on the client side)
+
+It returns the list of matching authorizations. Please note that all the matching authorizations available for the requested user will be returned including the one available to anonymous users. There is no need on the client side to combine the authorizations of the current, logged-in, user with the authorizations of anonymous users. 
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the uuid parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated and an eperson is specified
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators and the user specified in the eperson parameter can access
+
+## Other HTTP verbs than GET
+No other verbs are supported right now, these endpoints are all READ-ONLY. Authorizations cannot be grant or revoke directly, they are generated by the system via interaction with other endpoint such as the resourcepolicies, the submission, the workflow, etc.
+
+## Linked entities
+### EPerson
+**/api/authz/authorizations/<:string>/eperson**
+
+Return the eperson linked by this authorization
+
+Return codes:
+* 200 Ok - if the operation succeed and an eperson is set for this policy
+* 204 No content - if the authorization is related to anonymous users
+* 401 Unauthorized - if you are not authenticated and the authorization is not related to the Anonymous user
+* 403 Forbidden - if you are not logged in with sufficient permissions. See the requirement in the GET Single Authorization endpoint
+* 404 Not found - if the authorization doesn't exist
+
+### Object
+**/api/authz/authorizations/<:string>/object**
+
+Return the resource where the authorization is scoped.
+
+Return codes:
+* 200 Ok if the operation succeed
+* 401 Unauthorized - if you are not authenticated and the authorization is not related to the Anonymous user
+* 403 Forbidden - if you are not logged in with sufficient permissions. See the requirement in the GET Single Authorization endpoint
+* 404 Not found - if the authorization doesn't exist
+
+### Feature
+**/api/authz/authorizations/<:string>/feature**
+
+Return the feature resource that the user can access thanks to this authorization.
+
+Return codes:
+* 200 Ok if the operation succeed
+* 401 Unauthorized - if you are not authenticated and the authorization is not related to the Anonymous user
+* 403 Forbidden - if you are not logged in with sufficient permissions. See the requirement in the GET Single Authorization endpoint
+* 404 Not found - if the authorization doesn't exist

endpoints.md

@@ -36,6 +36,8 @@
 
 ## Endpoints Under Development/Discussion
 * [/api/authz/resourcepolicies](resourcepolicies.md)
+* [/api/authz/authorizations](authorizations.md)
+* [/api/authz/features](features.md)
 * [/api/statistics](statistics.md)
 * [/api/tools/itemrequests](item-requests.md)
 

features.md

@@ -0,0 +1,60 @@
+# Features Endpoints
+[Back to the list of all defined endpoints](endpoints.md)
+
+A feature is the representation of a business goal used in the [Authorization endpoint](authorizations.md) to declare what an user can do on a specific object.
+
+## Main Endpoint
+**/api/authz/features**
+
+List all the available features in the system. Access is restricted to system administrators.
+
+Parameters:
+* page, size [see pagination](README.md#Pagination)
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators can access
+
+## Single Feature
+**/api/authz/features/<:string>**
+
+Provide detailed information about a specific feature. Access is restricted to system administrators. The JSON response document is as follow
+
+```json
+{
+  "id": "withdrawItem",
+  "description": "The feature allows to withdrawn an item from the repository without deleting it. The restoreItem feature allow to undo the process",
+  "resourcetypes": [
+  	"item"
+  ],
+  "type": "feature"
+}
+```
+
+Attributes
+* id: the id of the feature is an unique shortname
+* description: an human readable description of the feature purpose 
+* resourcetypes: an array of types of objects where this feature apply in the textual, singular, lowercase, form. See org.dspace.core.Constants.typeText can be one of site, community, collection, item, bundle, bitstream, eperson, group, workspaceitem, workflowitem, pooltask, claimedtask
+
+Return codes:
+* 200 OK - if the operation succeed
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators can access
+* 404 Not found - if the authorization doesn't exist (or was already deleted)
+
+### Search methods
+#### resourcetype
+**/api/authz/features/search/resourcetype?type=<:string>**
+
+The supported parameters are:
+* page, size [see pagination](README.md#Pagination)
+* type: see org.dspace.core.Constants.typeText can be one of site, community, collection, item, bundle, bitstream, eperson, group, workspaceitem, workflowitem, pooltask, claimedtask
+
+It returns the list of features that apply to the specified type. 
+
+Return codes:
+* 200 OK - if the operation succeed
+* 400 Bad Request - if the type parameter is missing or invalid
+* 401 Unauthorized - if you are not authenticated
+* 403 Forbidden - if you are not logged in with sufficient permissions. Only system administrators can access