RAML files

Soldevelo teams: how are you writing the RAML files? Are you using a tool or rolling it by hand? We’ve noticed the requisition RAML file doesn’t load into Restlet Studio.

We also wondering if we should break up the RAML file into separate files, should they become so large it is difficult to read or maintain. Could our existing processes – to generate HTML doc, the testing, the swagger conversion – could they handle multiple RAML files?

We talked a bit about this in Seattle. We don’t want to be tied to a tool, but want to at least write acceptable RAML, preferably with some sort of validator. However we’re doing it now seems to be accepted by other tools (like RestAssured, swagger, etc.), so we can continue down what we’re doing for right now, but some validating assistance would be good.

Rich

Hi Rich,

If it comes to AYIC, we mostly use Restlet Studio for writing RAML files with small handmade adjustements (indentations, typos). I checked api-definition.yaml and also api-definition-raml-yaml (generated) and they both load into Restlet Studio.
Could you provide me the error message you got after unsuccessful load? Used RAML file would also be useful.

Kind regards,
Paweł Lal

···

On Tuesday, 2 August 2016 19:55:08 UTC+2, Rich Magnuson wrote:

Soldevelo teams: how are you writing the RAML files? Are you using a tool or rolling it by hand? We’ve noticed the requisition RAML file doesn’t load into Restlet Studio.

We also wondering if we should break up the RAML file into separate files, should they become so large it is difficult to read or maintain. Could our existing processes – to generate HTML doc, the testing, the swagger conversion – could they handle multiple RAML files?

We talked a bit about this in Seattle. We don’t want to be tied to a tool, but want to at least write acceptable RAML, preferably with some sort of validator. However we’re doing it now seems to be accepted by other tools (like RestAssured, swagger, etc.), so we can continue down what we’re doing for right now, but some validating assistance would be good.

Rich

Hey Pawel,

The import to Restlet Studio is working now because I fixed the issues in the RAML in this commit: https://github.com/OpenLMIS/openlmis-requisition/commit/fda4c8d1855f7bf2092480c7b4f55ba940e478bb . If you check out the previous commit, and try to import the RAML into Restlet Studio, you will see the errors.

Additionally, I am not sure how the file comes to its present format, as the export from Restlet Studio gives a very different RAML format than what is in source control. Can you explain how you take what you get from Restlet Studio and turn it into what is in the source?

Shalom,

Chongsun

– ​

There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Chongsun Ahn | chongsun.ahn@villagereach.org

Software Development Engineer

Village****Reach* ** Starting at the Last Mile*

2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA

DIRECT: 1.206.512.1536 **CELL: **1.206.910.0973 FAX: 1.206.860.6972

SKYPE: chongsun.ahn.vr

www.villagereach.org

Connect on Facebook****, Twitter** ** and our Blog

···

On Aug 3, 2016, at 8:31 AM, Paweł Lal plal@soldevelo.com wrote:

Hi Rich,

If it comes to AYIC, we mostly use Restlet Studio for writing RAML files with small handmade adjustements (indentations, typos). I checked api-definition.yaml and also api-definition-raml-yaml (generated) and they both load into Restlet Studio.

Could you provide me the error message you got after unsuccessful load? Used RAML file would also be useful.

Kind regards,

Paweł Lal

On Tuesday, 2 August 2016 19:55:08 UTC+2, Rich Magnuson wrote:

Soldevelo teams: how are you writing the RAML files? Are you using a tool or rolling it by hand? We’ve noticed the requisition RAML file doesn’t load into Restlet Studio.

We also wondering if we should break up the RAML file into separate files, should they become so large it is difficult to read or maintain. Could our existing processes – to generate HTML doc, the testing, the swagger conversion – could they handle multiple RAML files?

We talked a bit about this in Seattle. We don’t want to be tied to a tool, but want to at least write acceptable RAML, preferably with some sort of validator. However we’re doing it now seems to be accepted by other tools (like RestAssured, swagger, etc.), so we can continue down what we’re doing for right now, but some validating assistance would be good.

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/3246246d-ce84-40e0-a2a1-4519513d3b9b%40googlegroups.com.

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

Hi Chongsun,

As I see, RAML broke after change made by someone from the ToP, probably they use other way to edit it. The only manual change my team does during RAML creation is adding headers and body to response as well as indentations for code readability.

Best regards,
Paweł Lal

···

On Wednesday, 3 August 2016 20:59:16 UTC+2, chongsun.ahn wrote:

Hey Pawel,

The import to Restlet Studio is working now because I fixed the issues in the RAML in this commit: https://github.com/OpenLMIS/openlmis-requisition/commit/fda4c8d1855f7bf2092480c7b4f55ba940e478bb . If you check out the previous commit, and try to import the RAML into Restlet Studio, you will see the errors.

Additionally, I am not sure how the file comes to its present format, as the export from Restlet Studio gives a very different RAML format than what is in source control. Can you explain how you take what you get from Restlet Studio and turn it into what is in the source?

Shalom,

Chongsun

– ​

There are 10 kinds of people in this world; those who understand binary, and those who don’t.

Chongsun Ahn | chongs...@villagereach.org

Software Development Engineer

Village****Reach* ** Starting at the Last Mile*

2900 Eastlake Ave. E, Suite 230, Seattle, WA 98102, USA

DIRECT: 1.206.512.1536 **CELL: **1.206.910.0973 FAX: 1.206.860.6972

SKYPE: chongsun.ahn.vr

www.villagereach.org

Connect on Facebook****, Twitter** ** and our Blog

On Aug 3, 2016, at 8:31 AM, Paweł Lal pl...@soldevelo.com wrote:

Hi Rich,

If it comes to AYIC, we mostly use Restlet Studio for writing RAML files with small handmade adjustements (indentations, typos). I checked api-definition.yaml and also api-definition-raml-yaml (generated) and they both load into Restlet Studio.

Could you provide me the error message you got after unsuccessful load? Used RAML file would also be useful.

Kind regards,

Paweł Lal

On Tuesday, 2 August 2016 19:55:08 UTC+2, Rich Magnuson wrote:

Soldevelo teams: how are you writing the RAML files? Are you using a tool or rolling it by hand? We’ve noticed the requisition RAML file doesn’t load into Restlet Studio.

We also wondering if we should break up the RAML file into separate files, should they become so large it is difficult to read or maintain. Could our existing processes – to generate HTML doc, the testing, the swagger conversion – could they handle multiple RAML files?

We talked a bit about this in Seattle. We don’t want to be tied to a tool, but want to at least write acceptable RAML, preferably with some sort of validator. However we’re doing it now seems to be accepted by other tools (like RestAssured, swagger, etc.), so we can continue down what we’re doing for right now, but some validating assistance would be good.

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.

To view this discussion on the web visit https://groups.google.com/d/msgid/openlmis-dev/3246246d-ce84-40e0-a2a1-4519513d3b9b%40googlegroups.com.

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

If the same file works with some tools, but not with others, I am getting even more WSDL vibes from the good old days :slight_smile:

  Let's enforce using restlet studio - seems the more strict option and probably beats writing it by hand.

  Another note regarding RAML I would like to make - it would be good if services would expose it at runtime. Correct me if I'm wrong, but currently we only expose the Swagger spec. Exposing the RAML itself will allow using it with externally running tests etc.

On the earlier point, splitting the files eventually seems a good idea - created . Regards, Paweł
···

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

On 04.08.2016 09:39, Paweł Lal wrote:

Hi Chongsun,

    As I see, RAML broke after change made by someone from the ToP, probably they use other way to edit it. The only manual change my team does during RAML creation is adding headers and body to response as well as indentations for code readability.



    Best regards,

    Paweł Lal



    On Wednesday, 3 August 2016 20:59:16 UTC+2, chongsun.ahn wrote:

Hey Pawel,

          The import to Restlet Studio is working now because I fixed the issues in the RAML in this commit: [https://github.com/OpenLMIS/openlmis-requisition/commit/fda4c8d1855f7bf2092480c7b4f55ba940e478bb](https://github.com/OpenLMIS/openlmis-requisition/commit/fda4c8d1855f7bf2092480c7b4f55ba940e478bb)              . If you check out the previous commit, and try to import the RAML into Restlet Studio, you will see the errors.
          Additionally, I am not sure how the file comes to its present format, as the export from Restlet Studio gives a very different RAML format than what is in source control. Can you explain how you take what you get from Restlet Studio and turn it into what is in the source?


                      Shalom,

                      Chongsun

                      ​

                      -- ​

                      There are 10 kinds of people in this world; those who understand binary, and those who don’t.
                          Chongsun Ahn | chongs...@villagereach.org
  •                            Software Development Engineer*
    

Village****Reach* *Starting at the Last Mile

                          2900 Eastlake Ave. E, Suite 230,  Seattle, WA 98102, USA

DIRECT: 1.206.512.1536 **CELL: ** 1.206.910.0973 FAX: 1.206.860.6972

                          SKYPE: chongsun.ahn.vr

www.villagereach.org

                          Connect on **[Facebook](https://www.facebook.com/pages/VillageReach/103205113922)****,** **[Twitter](https://twitter.com/VillageReach)**** **and our **[Blog](http://villagereach.org/see-our-blog/thoughts-from-the-last-mile/)**

On Aug 3, 2016, at 8:31 AM, Paweł Lal <pl...@soldevelo.com > wrote:

                  Hi Rich,



                  If it comes to AYIC, we mostly use Restlet Studio for writing RAML files with small handmade adjustements (indentations, typos). I checked api-definition.yaml and also api-definition-raml-yaml (generated) and they both load into Restlet Studio. 

                  Could you provide me the error message you got after unsuccessful load? Used RAML file would also be useful.



                  Kind regards,

                  Paweł Lal





                  On Tuesday, 2 August 2016 19:55:08 UTC+2, Rich Magnuson wrote:
                          Soldevelo teams:  how are you writing the RAML files?  Are you using a tool or rolling it by hand?  We’ve noticed the requisition RAML file doesn’t load into Restlet Studio.
                          We also wondering if we should break up the RAML file into separate files, should they become so large it is difficult to read or maintain.  Could our existing processes – to generate HTML doc, the testing, the swagger conversion – could they handle multiple RAML files?
                          We talked a bit about this in Seattle.  We don’t want to be tied to a tool, but want to at least write acceptable RAML, preferably with some sort of validator.  However we’re doing it now seems to be accepted by other tools (like RestAssured, swagger, etc.), so we can continue down what we’re doing for right now, but some validating assistance would be good.

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.

                                      To view this discussion on the web visit [https://groups.google.com/d/msgid/openlmis-dev/3246246d-ce84-40e0-a2a1-4519513d3b9b%40googlegroups.com](https://groups.google.com/d/msgid/openlmis-dev/3246246d-ce84-40e0-a2a1-4519513d3b9b%40googlegroups.com?utm_medium=email&utm_source=footer).

                                      For more options, visit [https://groups.google.com/d/optout](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/7f1a2932-4184-4661-9188-05752caf61a0%40googlegroups.com](https://groups.google.com/d/msgid/openlmis-dev/7f1a2932-4184-4661-9188-05752caf61a0%40googlegroups.com?utm_medium=email&utm_source=footer).

  For more options, visit [https://groups.google.com/d/optout](https://groups.google.com/d/optout).

Hey Pawel,

So I am still confused—your team is using Restlet Studio? If so, how does the file come to this format? If I import the RAML into Restlet Studio and export it back out, the format is quite different. Attached are two files:

api-definition-raml.yaml (63.8 KB)

ATT00001.htm (215 Bytes)

raml.yaml (55.2 KB)

ATT00002.htm (27.1 KB)

Hello Chongsun,

I talked with Chris and obviously not everyone was using Restlet Studio to edit RAML. Moreover, we have also made formatting changes manually, as the JSONs generated by Restlet aren't really very readable. I know that people have also been manually editing the RAML file in case of merges (something else was merged to the repository RAML while they were working on it). Other than the formatting and the order of the entries, I don't think there are any big changes?

I propose, that as Pawel mentioned, we just stick to the Restlet Studio for now. If everyone is just taking the file and uploading it to the Restlet Studio, I suppose we can even neglect formatting it to the more readable format and just commit the intact output from the Restlet Studio. Does that sound OK to everyone? If yes, the next person adding/editing the RAML may just commit the direct output from the Restlet Studio.

Best regards,

Sebastian Brudzinski.
···

On 04.08.2016 19:25, Chongsun Ahn wrote:

Hey Pawel,

    So I am still confused—your team is using Restlet Studio? If so, how does the file come to this format? If I import the RAML into Restlet Studio and export it back out, the format is quite different. Attached are two files:

  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/027A7E74-D439-45D4-8B4D-606FAD1C1686%40villagereach.org?utm_medium=email&utm_source=footer)      . For more options, visit .

https://groups.google.com/d/msgid/openlmis-dev/027A7E74-D439-45D4-8B4D-606FAD1C1686%40villagereach.org
https://groups.google.com/d/optout

Regarding Restlet Studio, my understanding is that Restlet Studio 1) doesn’t support RAML v1 and 2) doesn’t support everything within the RAML spec.

I do agree that a visual editor of RAML seems useful, however I wouldn’t expect us to standardize our RAML based on a tool that is less capable than RAML itself.

There are other intellisense-type/non-visual tools, such as API Workbench, which help in editing RAML, though one of the reasons that RAML was suggested was due to it’s easier readability as a YAML file over the alternative Swagger spec in JSON. If in part the challenges with authoring and maintaining RAML at present is the size it has grown to, approx 1k lines, I would suggest two strategies could help with this:

  1. Split the services, a lot of these definitions are in one file because reference data and requisition is all together - I know this is a current work item
  2. Split the responsibilities of the api spec into multiple files - ideally along the lines where developers whom are working on separate interfaces of a service wouldn’t be worried about merge conflicts of the one interface definition file. This later one a quick google search leads this as promising: https://github.com/raml2html/raml2html/issues/132
    Finally, mentioned far earlier in this thread was an issue of importing our RAML into Restlet studio and this too seems like a red herring on the part of Restlet Studio - I ran the same “faulty” RAML through our current ramlTo documentation tasks as well as utilized raml-cop, a tool which claims to validate RAML files to RAML spec, and neither found the issues that Restlet Studio found. This leads me to favor abandoning the use of Restlet Studio for authoring RAML for anything but prototype interface specification.

Best,

Josh

···

On Friday, August 5, 2016 at 4:39:41 AM UTC-7, Sebastian Brudziński wrote:

Hello Chongsun,

I talked with Chris and obviously not everyone was using Restlet Studio to edit RAML. Moreover, we have also made formatting changes manually, as the JSONs generated by Restlet aren't really very readable. I know that people have also been manually editing the RAML file in case of merges (something else was merged to the repository RAML while they were working on it). Other than the formatting and the order of the entries, I don't think there are any big changes?



I propose, that as Pawel mentioned, we just stick to the Restlet Studio for now. If everyone is just taking the file and uploading it to the Restlet Studio, I suppose we can even neglect formatting it to the more readable format and just commit the intact output from the Restlet Studio. Does that sound OK to everyone? If yes, the next person adding/editing the RAML may just commit the direct output from the Restlet Studio.



Best regards,

Sebastian Brudzinski.


  On 04.08.2016 19:25, Chongsun Ahn wrote:

Hey Pawel,

    So I am still confused—your team is using Restlet Studio? If so, how does the file come to this format? If I import the RAML into Restlet Studio and export it back out, the format is quite different. Attached are two files:

  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/027A7E74-D439-45D4-8B4D-606FAD1C1686%40villagereach.org?utm_medium=email&utm_source=footer)[https://groups.google.com/d/msgid/openlmis-dev/027A7E74-D439-45D4-8B4D-606FAD1C1686%40villagereach.org](https://groups.google.com/d/msgid/openlmis-dev/027A7E74-D439-45D4-8B4D-606FAD1C1686%40villagereach.org).

  For more options, visit [https://groups.google.com/d/optout](https://groups.google.com/d/optout).