OpenLMIS API endpoints

65 views
Skip to first unread message

Rich Magnuson

unread,
Jul 27, 2016, 7:47:01 PM7/27/16
to openlm...@googlegroups.com

Thanks to the HTML doc of our interfaces, I could easily browse through most of the endpoints written to date.  I see a query pattern that goes against the style guide.  Many entities specify a /search path, but instead of using query parameters, use very specific endpoints.  For example, the /orders resource has endpoints like:

 

/orders/csv/{id}/search/findBySupplyingFacility

/orders/csv/{id}/search/findBySupplyingFacilityAndRequestingFacility

/orders/csv/{id}/search/findBySupplyingFacilityAndProgram

/orders/csv/{id}/search/findBySupplyingFacilityAndRequestingFacilityAndProgram

 

 

The requisitions resource, however, has a single /search endpoint that takes a number of parameters.  This is the method specified in the style guide.

 

Unless there is a specific need, all new APIs should prefer search parameters.  Each parameter should have documentation (Is it an integer?  UTC date?  UUID?  String?  Are wildcards supported?  Is it required?). 

 

I have a few more questions on how sorting and paging are handled, but haven’t had the chance to look deeper.  I would like to hear from the team and tech leads on specifics we should adhere to, and put into the style guide.

 

Rich

Sebastian Brudziński

unread,
Jul 28, 2016, 11:10:17 AM7/28/16
to openlm...@googlegroups.com
Hello,

thanks for identifying this problem, Rich. I've taken the freedom and created a ticket in the current sprint to refactor those endpoints to use query parameters, similar to what is done in requisitions: https://openlmis.atlassian.net/browse/OLMIS-872  Does that sound all right?

Concerning sorting and pagination - only the resources exposed via SDR allow for sorting and paginating at this point. Our custom MVC search endpoints do not have that implemented yet. I think it would make sense to create some kind of a generic paging/sorting solution, that could be reused by all our MVC search endpoints. How does that sound? Should we go ahead and create a ticket for that as well? I'm also wondering if all our search endpoints should expose paging/sorting option or only some selected ones.

Concerning the style guide, the sorting of the instances is already described - a "sort" parameter should be used and take the field name as a value, preceeded with a minus '-' if the order is meant to be descending. We may go with "page" and "pageSize" or "limit" for pagination.

Best regards,
Sebastian Brudziński.
--
You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/BN1PR02MB021CBDE8445A62BBEE5446A930F0%40BN1PR02MB021.namprd02.prod.outlook.com.
For more options, visit https://groups.google.com/d/optout.

Rich Magnuson

unread,
Jul 28, 2016, 4:43:15 PM7/28/16
to Sebastian Brudziński, openlm...@googlegroups.com

Hi Sebastian,

 

OLMIS-872 sounds good.  Whoever grabs it should post a list of the decremented endpoints and proposed query parameter list (I’ll add that to the story).  This is important as we’re also continuing with test automation, so we don’t want to automate endpoints that are going away.

 

I like the idea of some boilerplate solution for paging/sorting on MVC endpoints.  Yes, please create an issue for it.  IMO, any resource that would be exposed via UI should support sorting and pagination.   

 

Thanks – Rich

skaczorowski

unread,
Jul 29, 2016, 5:58:54 AM7/29/16
to OpenLMIS Dev
Hi Rich,
I identified following endpoints which needs change:

1. Order:
  • /orders/search/findBySupplyingFacility
  • /orders/search/findBySupplyingFacilityAndRequestingFacility
  • /orders/search/findBySupplyingFacilityAndProgram
  • /orders/search/findBySupplyingFacilityAndRequestingFacilityAndProgram
proposed change:
  • /orders/search?supplyingFacility=x&requestingFacility=x&program=x
parameters:
  • supplyingFacility - required
  • requestingFacility - not required
  • program - not required

2. User:
  • /users/search/findByUsername
  • /users/search/findByFirstName
  • /users/search/findByLastName
  • /users/search/findByFirstNameAndLastName
  • /users/search/findByHomeFacility
  • /users/search/findByActive
  • /users/search/findByVerified
proposed change:
  • /users/search?username=x&firstName=x&lastName=x&homeFacility=x&active=x&verified=x
parameters:
  • username - not required
  • firstName - not required
  • lastName - not required
  • homeFacility - not required
  • active - not required
  • verified -  not required

3. ProductCategory:
  • /productCategories/search/findByCode
proposed change:
  • /productCategories/search?code=x
parameters:
  • code - not required

4. Period:
  • /periods/search/findByProcessingSchedule
  • /periods/search/findPreviousPeriods
proposed change:
  • /periods/search?processingSchedule=x&startDate=x
parameters:
  • processingSchedule-required
  • startDate - not required

5. ProgramProduct:
  • /programProducts/search/findByProgram
  • /programProducts/search/findByProgramAndFullSupply
proposed change:
  • /programProducts/search?program=x&fullSupply=x
parameters:
  • program - required
  • fullSupply - not required

6. Stock:
  • /stocks/search/findByStockInventoryAndProduct
proposed change:
  • /stocks/search?stockInventory=x&product=x
parameters:
  • StockInventory - required
  • Product - required

7. SupplyLine:
  • /supplyLines/search/findByProgramAndSupervisoryNode
proposed change:
  • /stocks/search?program=x&supervisoryNode=x
parameters:
  • program - required
  • supervisoryNode - required

8. RequisitionLine
  • /requisitionLines/search/findByRequisitionAndProduct
proposed change:
  • /requisitionLines/search?requisition=x&product=x
parameters:
  • requisition - required
  • product - required

9. Requisition:
  • /requisitions/search/findByProcessingPeriodAndFacilityAndProgram
  • /requisitions/search/findBySupervisoryNode
  • /requisitions/search/findByStatus
proposed change:
  • /requisitions/search?facility=x&program=x&status=x&supervisoryNode=x&processingPeriod=x
parameters:
  • facility - not required
  • program - not required
  • status - not required
  • supervisoryNode - not required
  • processingPeriod - not required

10. RequisitionTemplate:
  • /requisitionTemplates/search/findByProgram
proposed change:
  • /requisitions/search?program=x
parametrs:
  • program - not required

Rich Magnuson

unread,
Jul 29, 2016, 5:35:44 PM7/29/16
to skaczorowski, OpenLMIS Dev

Thanks Szymon.  That list looks good to me.  I’m sure we’ll add to the query parameter lists as we continue building domain and UI.

 

Do string parameters support any special or wildcard characters?  I think we will want this eventually, but have to take some care in implementing it (e.g. to prevent runaway queries, SQL injection, etc.).

 

Rich

--

You received this message because you are subscribed to the Google Groups "OpenLMIS Dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to openlmis-dev...@googlegroups.com.
To post to this group, send email to openlm...@googlegroups.com.

skaczorowski

unread,
Aug 9, 2016, 5:51:59 AM8/9/16
to OpenLMIS Dev, skaczo...@soldevelo.com
Hi Rich,
sorry for late reply. Currenty searches don't support any wildcards characters. We will have to write some custom methods to handle them. 

To post to this group, send email to openl...@googlegroups.com.

Reply all
Reply to author
Forward
0 new messages