REST design issues

This is a list of issues with REST implementation that are still not resolved. Here is Read the Docs page about REST design and OLMIS dev forum post

List is ordered so the issue with the highest priority that should be done first are on the top.

  • Some of our 'searching' endpoints are omitting parameters, it can confuse users if some valid search parameters are not taken into consideration OLMIS-3857 - Getting issue details... STATUS :
    • /api/facilities GET endpoint omits all other parameters if 'id' parameter is passed  OLMIS-3704 - Getting issue details... STATUS
    • /api/users GET endpoint omits all other parameters if 'id' parameter is passed  OLMIS-3705 - Getting issue details... STATUS
    • /api/catalogItems GET endpoint omits all other parameters if 'format' parameter is passed  OLMIS-3706 - Getting issue details... STATUS
  • We have /api/facilities/minimal GET endpoint which is returning facilities with only id and name properties OLMIS-3858 - Getting issue details... STATUS , it can be resolved by:
  • Swagger have problems with endpoints that can return or accept multiple types of data (i.e. /api/catalogItems can return application/json and text/csv content types) OLMIS-3859 - Getting issue details... STATUS . Here are 2 related tickets: OLMIS-3231 - Getting issue details... STATUS and OLMIS-3232 - Getting issue details... STATUS . It could  be resolved by:
    • replacing Swagger UI with something more native to Swagger i.e. API Console  OLMIS-3708 - Getting issue details... STATUS  Q: do we have a better one?
  • Our PUT /api/{resource}/{id} endpoints do not allow creating objects with specified 'id'  OLMIS-3860 - Getting issue details... STATUS
  • We need to introduce expanded REST api pattern:   OLMIS-3667 - Getting issue details... STATUS
  • In Requisition service we have api/requisitions/forConvert /api/requisitions/submitted endpoints and retrieving those requisitions should probably be done using GET /api/requisition/ endpoint  OLMIS-3723 - Getting issue details... STATUS
  • We should merge /api/{resource} GET endpoints with /api/{resource}/search endpoints in all places that it is possible and will not introduce problem with searching like with extraData property, we should fix them on the occasion, not in separate tickets:
    • /api/geographicZones/search
    • /api/lots/search
    • /api/requisitions/search
    • /api/requisitionTemplate/search
    • /api/transferProperties/search
    • /api/orders/search
    • /api/supervisoryNodes/search
    • /api/supplyLines/search
    • /api/stockAdjustmentReasons/search
    • /api/rights/search
    • /api/requisitionGroups/search
    • /api/programs/search
    • /api/facilities/search
    • /api/users/search
    • /api/users/rightSearch
    • /api/facilities/byBoundary →  OLMIS-3772 - Getting issue details... STATUS
  • We are still using '/print' endpoints
  • Requisition resource is still using actions like submit/approve/skip, Here is a solution that we want to end up with:  OLMIS-3709 - Getting issue details... STATUS
  • Search parameters in some places are confuisng i.e. we have 'facility' instead of 'facilityId' or 'facilityCode'

OpenLMIS: the global initiative for powerful LMIS software