search

amarbajric / EBUSA-AIM17

BPMaaS. Platform for buying, selling and reviewing processes
MIT License
2 stars 3 forks source link

API Documentation #81

Closed tortmann closed 6 years ago

tortmann commented 6 years ago

The use of tools like SwaggerAPI are required!

For more details see document on SharePoint: /Development/APs_Requirements/EBUSA_SWD_APs_29.04.18.pdf

deKilla commented 6 years ago

I have designed a basic swagger document that is in desperate need of further adaptations. However, since the API (in its current state) is far from final this is about as good as gets (for now).

https://fhjoanneum.sharepoint.com/:u:/s/EBUSA-Projekt/Efyo2f5AO8NLiydOPJPCGfsBhXMj9YX55RzNtAkAJ_A_0w?e=wJ5s8E

edit: the git branch that I have initially created is obsolete as there are no changes

amarbajric commented 6 years ago

First of all I would suggest to use a feature-branch for this task, as an API documentation should also reside in a repository. Hence, it is important to include it into a separate folder like api-documentation to give other a quick overview over all available endpoints.

Furthermore, I have some issues I want to comment on. Please refer to the screenshot below. screen shot 2018-06-05 at 09 40 01

ISSUE 1 Keep in mind that we want to include every service in this api-documentation. As the process store and other services will be provided under a different port, we will need to categorize the api documentation. If this is not possible (which I doubt), then we need to make separate files for each service and its enpoints.

ISSUE 2 When working with REST and a token-based authentication system, there normally is no endpoint where a user can log-off. As long as the user has a valid token, this token can be used to get data from the protected endpoints. Logging off simply means to dump the local storage of the browser where the token is saved temporary. This has to be done client side.

ISSUE 3 Except the login, register and checkIfMailTaken endpoints, EVERY other endpoint is only reachable under the prefixed path /api/.... Reason: If the endpoint does not include /api/ in it, this resource is not protected (does not need auth.). If however, the endpoint does not include /api/ in its path, the resource is not protected, and this is only necessary for the functionality mentioned above. Further, we do not provide any endpoint for deleting a user. We only allow for user creation (register), user querying (get all and single) or for a user update.

tortmann commented 6 years ago

1) The API documentation should definitely be added to repository as it provides vital information for any further development of this project and the file on SharePoint can not be accessed by anyone outside this project team.

2) as @amarbajric mentioned logout does not an endpoint and should be implemented similar to the implementation in the PIAEN project

3) it is important to note that this documentation should regularly be updated each time new endpoint or changes are implemented so provide a reliable and up-to-date source of information