Introducing expanded DTO representation for new endpoints - step-by-step guide

Hello everyone,

  as we agreed at the showcase yesterday, I'm attaching a simple step-by-step guide on the usage of the expanded REST API pattern in our services. For the high-level overview, see the docs:

Adding expandible representation for a new endpoint:

  1. Make sure that the service, where you intend to use the pattern, already has got the **ObjReferenceExpander**
  component. If it doesn't, move it from any other service that does.

  2. Make sure that the service has got a compile dependency on the latest version of **openlmis-service-util**

  3. Create DTO classes that represent the expanded version of the referenced entity. Those classes must inherit from the **ObjectReferenceDto**
  class.

  4. Edit the endpoint that is supposed to handle DTO expansion, by adding a new query parameter, called **expand** (not required, a collection of string inputs), eg.
@RequestParam(value = "expand", required = false) List<String> expands
  1. Call the expandDto method of the ObjectReferenceExpander , with the DTO that you wish to expand and the expands
    collection, taken from the query parameter of the endpoint.

  2. Modify the RAML for that endpoint, by adding expandible trait. If that trait doesn’t exist yet, create one, based on any other service that already has it.

  3. Make sure it works!

    We will also be discussing the pattern at the next tech committee call if you have got any questions.

Best regards,

  Sebastian.
···

http://openlmis.readthedocs.io/en/latest/conventions/codeStyleguide.html#restful-interface-design-documentation

      Sebastian Brudziński

    Software Developer / Team Leader

sbrudzinski@soldevelo.com

SolDevelo
Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41

Just to be specific, yesterday on the showcase I was talking about getting rid of steps 4 and 5 by introducing a something along the lines of an interceptor or controller advice. We are currently holding off on that until the pattern matures.

Regards,

Paweł


SolDevelo
Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41

···

On Thu, Dec 7, 2017 at 11:08 AM, Sebastian Brudziński sbrudzinski@soldevelo.com wrote:

Hello everyone,

  as we agreed at the showcase yesterday, I'm attaching a simple step-by-step guide on the usage of the expanded REST API pattern in our services. For the high-level overview, see the docs: [http://openlmis.readthedocs.io/en/latest/conventions/codeStyleguide.html#restful-interface-design-documentation](http://openlmis.readthedocs.io/en/latest/conventions/codeStyleguide.html#restful-interface-design-documentation)

Adding expandible representation for a new endpoint:

  1. Make sure that the service, where you intend to use the pattern, already has got the **ObjReferenceExpander**
  component. If it doesn't, move it from any other service that does.
  2. Make sure that the service has got a compile dependency on the latest version of **openlmis-service-util**
  3. Create DTO classes that represent the expanded version of the referenced entity. Those classes must inherit from the **ObjectReferenceDto**
  class.
  4. Edit the endpoint that is supposed to handle DTO expansion, by adding a new query parameter, called **expand** (not required, a collection of string inputs), eg.
@RequestParam(value = "expand", required = false) List<String> expands
  1. Call the expandDto method of the ObjectReferenceExpander , with the DTO that you wish to expand and the expands
    collection, taken from the query parameter of the endpoint.
  1. Modify the RAML for that endpoint, by adding expandible trait. If that trait doesn’t exist yet, create one, based on any other service that already has it.
  1. Make sure it works!
  We will also be discussing the pattern at the next tech committee call if you have got any questions.

Best regards,

  Sebastian.


Sebastian Brudziński

    Software Developer / Team Leader


     sbrudzinski@soldevelo.com


SolDevelo
Sp. z o.o. [LLC] / www.soldevelo.com
Al. Zwycięstwa 96/98, 81-451, Gdynia, Poland
Phone: +48 58 782 45 40 / Fax: +48 58 782 45 41

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/9ef9da64-c30a-1279-3826-7610074b1d38%40soldevelo.com.

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

Paweł Gesek

    Technical Project Manager

     pgesek@soldevelo.com / +48 690 020 875