OpenLMIS API endpoints

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

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:   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.
···

https://openlmis.atlassian.net/browse/OLMIS-872

  On 28.07.2016 01:46, Rich Magnuson wrote:
      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

  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+unsubscribe@googlegroups.com.

  To post to this group, send email to openlmis-dev@googlegroups.com.

  To view this discussion on the web visit [](https://groups.google.com/d/msgid/openlmis-dev/BN1PR02MB021CBDE8445A62BBEE5446A930F0%40BN1PR02MB021.namprd02.prod.outlook.com?utm_medium=email&utm_source=footer)      . For more options, visit .

https://groups.google.com/d/msgid/openlmis-dev/BN1PR02MB021CBDE8445A62BBEE5446A930F0%40BN1PR02MB021.namprd02.prod.outlook.com
https://groups.google.com/d/optout

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

···

From: openlmis-dev@googlegroups.com [mailto:openlmis-dev@googlegroups.com] On Behalf Of Sebastian Brudzinski

Sent: Thursday, July 28, 2016 8:10 AM

To: openlmis-dev@googlegroups.com

Subject: Re: [openlmis-dev] OpenLMIS API endpoints

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.

On 28.07.2016 01:46, Rich Magnuson wrote:

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

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@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.

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@googlegroups.com.

To view this discussion on the web visit
https://groups.google.com/d/msgid/openlmis-dev/579A2053.90502%40soldevelo.com
.

For more options, visit https://groups.google.com/d/optout.

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

W dniu czwartek, 28 lipca 2016 01:47:01 UTC+2 użytkownik Rich Magnuson napisał:

···

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

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

···

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

W dniu czwartek, 28 lipca 2016 01:47:01 UTC+2 użytkownik Rich Magnuson napisał:

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

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+unsubscribe@googlegroups.com.

To post to this group, send email to
openlmis-dev@googlegroups.com.

To view this discussion on the web visit
https://groups.google.com/d/msgid/openlmis-dev/af2cf6a8-ef3a-423f-a0e3-646e34afee68%40googlegroups.com
.

For more options, visit https://groups.google.com/d/optout.

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.

···

On Friday, 29 July 2016 23:35:44 UTC+2 user Rich Magnuson wrote:

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

From: openlm...@googlegroups.com [mailto:openlm...@googlegroups.com] On Behalf Of skaczorowski

Sent: Friday, July 29, 2016 2:59 AM

To: OpenLMIS Dev openlm...@googlegroups.com

Subject: [openlmis-dev] Re: OpenLMIS API endpoints

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

W dniu czwartek, 28 lipca 2016 01:47:01 UTC+2 użytkownik Rich Magnuson napisał:

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

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
openl...@googlegroups.com.

To view this discussion on the web visit
https://groups.google.com/d/msgid/openlmis-dev/af2cf6a8-ef3a-423f-a0e3-646e34afee68%40googlegroups.com
.

For more options, visit https://groups.google.com/d/optout.