Development Guidelines - uzh/marugoto GitHub Wiki

Repositories

Backend

Coding guidelines

  • We will use marugoto_settings.xml file for coding style. It is placed in the repository root folder. To import this settings do the following:

    • Open Spring Tool Suite > Preferences  (on Windows go to Window/Preferences)
    • Choose Java > Code Style > Formatter
    • On the top of the pop-up window select import button and choose marugoto_settings.xml from project root
    • Click Apply and Close

  • We don't use shortened version of an if else command

  • The business logic is in the service and not in the controller or the model

  • Header for java-file (not final!)

/**
 * short description
 */
  • Unit-Tests:**
    **
    • Controller-Tests
    • Repository-Tests
    • Service-Tests
    • Data-Validation-Tests

Because we have only simple getters and setters in entities, we do not do Entity-Tests. And partly they are done in the repository tests

URL scheme

Based on the following guide: https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Retrieving entities:

GET /pages/list - Retrieves a list of tickets
GET /pages/12 - Retrieves specific page #12
POST /pages - Creates a new page
PUT /pages/12 - Update page #12
DELETE /pages/12 - Deletes page #12

Retrieving nested entities:

GET /tickets/12/messages/list - Retrieves list of messages for ticket #12
GET /tickets/12/messages/5 - Retrieves message #5 for ticket #12
POST /tickets/12/messages - Creates a new message in ticket #12
PUT /tickets/12/messages/5 - Updates message #5 for ticket #12
DELETE /tickets/12/messages/5 - Deletes message #5 for ticket #12

Suppling request parameters (query parameters):

GET /tickets?sort=priority - Retrieves a list of tickets in ascending order of priority

URL naming

We use spinal-case for REST URLs for better readability and no capitalization dependency (all lowercase).

Naming guide: https://restfulapi.net/resource-naming/

Example URLs:

https://marugoto.uzh.ch/story-management/do-something 
https://marugoto.uzh.ch/story-management/do-something/{this-is-an-id}
https://marugoto.uzh.ch/states/{id}/do-something-with-it

https://marugoto.uzh.ch/story-management/modules?sort=createdAt&sort-direction=ASC
⚠️ **GitHub.com Fallback** ⚠️