API === This page is interesting to developers of Project-W, but also to people who want to write custom clients for it (like bash or python scripts or anything else). If the latter is the case then focus on the client-facing routes and ignore the runner-facing ones. .. note:: If you want to develop a client that is intended to replace the current frontend (not just as an addition) then make sure that is has both an ``/activate`` and a ``/resetPassword`` route! The backend expects that the client has these since it puts them into the emails it sends to the users. Both routes should accept a ``token`` as a query string that contains the activation/password reset token. If you don't do this, then the links in the emails the backend sends to the users will not work for your client. .. _general-label: General ------- The REST API of the backend is divided into three sections: 1. /api/users/* 2. /api/jobs/* 3. /api/runners/* The first two are for the client and include routes to manage users and their jobs respectively. From now on we will call them client-facing routes. The third one is for the communication between the backend and its runners and should be ignored by the clients (runner-facing routes). We made the following design decision regarding when to use GET, POST or PUT routes: - **GET**: Requests are both safe and idempotent - **PUT**: Requests are not safe but idempotent - **POST**: Requests are neither safe nor idempotent A safe operation is one that doesn't cause a write to the database (only read). An idempotent request is one that returns the same data regardless of how often you request it (e.g. the returned data of the 10th request will be the same as the one of the 1st). Additionally to the http status codes all client-facing routes will return a json object with a ``msg`` attribute which is string containing the response of the server in (more or less) human readable form. All responses in ``msg`` sent by client-facing routes are written in a way such that they can directly be displayed on the frontend of the client. However with some invalid requests the response may be generated by Flask, in these cases the ``msg`` attribute will still be present but maybe not as understandable by the user. All negative responses (i.e. responses that do not have http status code 200) generated by client-facing routes (and not Flask itself) also return an ``errorType`` attribute in their json response that will contain a string with the type of error the server encountered with this request. Refer to :ref:`error_types-label` for all strings we use for this. Quick reference --------------- .. qrefflask:: project_W.app:create_app(customConfigPath="..") :undoc-static: Routes in detail ---------------- .. autoflask:: project_W.app:create_app(customConfigPath="..") :endpoints: :include-empty-docstring: :undoc-static: :order: path .. _error_types-label: Error types ----------- Why do we need error types? Sometimes the client wants to have additional information about why a particular request failed that can easily be automatically processed. For example if you have a Signup form the client may want to highlight the field in the frontend that caused the error. So if the errorType is `email` then highlight the email field. If it is `password` then highlight the password field. For consistency reasons and to make client programming easier (so you don't have to check all the time if the errorType attribute exists and is not null this time) we included this field on all negative responses (i.e. responses that do not have http status code 200) that get generated by all client-facing routes (and not Flask itself). The following strings can be returned in the ``errorType`` attribute. Please note that we may add additional types with future updates if necessary. - serverConfig - error due to configuration of server - e.g.: disableSignup is set in config - email - error due to email being invalid in some way - e.g. when trying to signup or changing email to something that is not an email address - not for login or any kind of authentication, only when it is NOT an authentication parameter (see auth for that)! - password - error due to password being invalid in some way - e.g. when trying to signup or changing password to something invalid like a password which is too short - not for login or any kind of authentication, only when it is NOT an authentication parameter (see auth for that)! - invalidRequest - a generic error type for if the request that you made was somehow invalid (probably regarding the query string/form attributes you used) - If `email` and `password` wouldn't have their own more specific error type, then they would also fall into this category - e.g. if the provided list of jobIds in /jobs/info isn't formatted correctly - permission - user doesn't have permission to access this route/resource/feature - e.g. admin exclusive routes, user tries to modify other users or the user is not activated even though that is required for this route - often combined with http status code 403 - not for authentication failures, see auth for that! - auth - authentication failed for some reason - e.g. invalid credentials, invalid password, invalid token, etc. - notInDatabase - requested ressource is not in database - e.g. when no user with the provided email address could be found in the database - operation - invalid operation at this time (e.g. some condition for this operation that is not part of the request itself is not met) - e.g. activate_user when user is already activated