Results 1 to 8 of 8

Thread: RESTGen

  1. #1
    Join Date
    Mar 2009
    Location
    Beech Hill - a village near Reading in the UK
    Posts
    2,812

    Default RESTGen

    Since I have used it in a number of presentations, and also distributed it to attendees at my recent OAuth2 and REST courses at EDUC 2016, I thought I should make this little program publicly available.

    Note: it comes with exactly no warranty - use at your own risk! That said, I have used it to create all of the structs and handler code for the MS Office 365 API, so it has received substantial testing.

    What it does is basically take JSON data and generates DataFlex structs to hold that data (otherwise a very tedious and error-prone process), along with code to convert from JSON to struct variables and visa-versa.

    You paste sample JSON into the big edit window, give the base struct a name, give inner structs a name prefix (defaults to the outer struct name - stick with that unless you are sure you know better), tell it where you want to put the generated packages and where that is in relation to your AppSrc directory. You can also set the indentation level to match your preference.

    The way I use it is to add it to my Studio "Tools" menu (in the Studio, "Tools" -> "Configure Tools Menu..."), adding a "<workspace>" parameter, which allows the program to default to putting the generated packages somewhere sensible. That way you need only paste in the JSON, give the outer struct a sensible name then click generate and the packages will be placed in your workspace's AppSrc\ApiStructs folder (which will be created if it does not already exist).

    When it runs it will give a summary of what it is doing in an output window, along with any warnings. The most common warning is that it has encountered an empty array in the sample JSON, so does not know what "type" of data the array should hold - it will default that type to String, but if that is wrong, you should correct the JSON and hit "Generate" again, overwriting the previously generated packages (warning: it does that silently, so name things carefully!).

    There is a limit to the amount of JSON the text window can hold, so you might need to trim large JSON. To that end, be aware that it only examines the first element in each array to determine the type of the array elements, so having an array with many elements is one thing you can cut out (leave in the best populated example).

    Once you have generated your struct packages, you need only "Use" the outer one in your code - it will "Use" any inner ones (recursively if required), then create a variable of the type name you gave it. Then there are two procedures you can call to work with the data, passing the two arguments by reference:

    Code:
    Use ApiStructs\TheNameYouGave.pkg
    
    ...
    
        TheNameYouGave tData
        String sJson
    
        // To populate a struct variable from JSON:
        Send JsonStringToStruct of oStructHandler_TheNameYouGave (&sJson) (&tData)
    
        // To generate JSON from the contents of a struct variable:
        Send StructToJsonString of oStructHandler_TheNameYouGave (&tData) (&sJson)
    As well as generating handler code, it also generates translations, so that if the JSON contained member names which could not be used as DataFlex struct member names (Microsoft's "@odata.xxxxx" names being one example, but there are many others) it will translate them both going in and out, so on the way in "@odata.id" would become the struct member name "_odata_id", while on the way out "_odata_id" would become "@odata.id" in the generated JSON.

    A minor tip: the Studio will do a better job of prompting you with the right member names if you open the packages concerned in it (I tend to just right-click on the type name and select "Go To Definition").

    RESTGen.zip

    You should unzip the file into its own directory and run RESTGen from there. This version is for DF 18.2 - if you need an 18.1 version, just let me know.

    Please report bugs etc. here, so everybody can benefit.

    Mike

  2. #2
    Join Date
    Mar 2009
    Location
    Beech Hill - a village near Reading in the UK
    Posts
    2,812

    Default Re: RESTGen

    Now that I have posted RESTGen, I should discuss one of its weaknesses.

    When dealing with JSON which contains multiple versions of the same basic type, the program is too dumb to figure that out, resulting in redundant production of types and incompatibility between them.

    For example, if you were to paste the sample JSON for an e-mail message in and generate the required packages, the program does not know that a Sender is actually the same underlying type as a Recipient, which is the same as a CC-Recipient, which is the same as a BCC-Recipient, which is the same as a Reply-To, so it generates a type for each... and you then cannot freely move one to another (which can be a bit of a pain).

    The only answer I know of is, I'm afraid, to go into the generated code and amend it by hand, doing a lot of find-and-replacing. Given the complexity of the generated code, this can be a pretty daunting prospect, but be brave - it is worth doing and if you mess up, you can alway just generate it all again from the original JSON.

    Mike
    Last edited by Mike Peat; 17-May-2016 at 11:21 AM. Reason: redundant "in"

  3. #3
    Join Date
    Feb 2009
    Location
    Pine Island, Forida
    Posts
    2,076

    Default Re: RESTGen

    Wouldn't it make sense for you to just release the edited packages?
    Frank Valcarcel
    Cove Systems, Inc.
    Pine Island, Florida USA
    fv@covesys.com
    (239) 823-7976

  4. #4
    Join Date
    Mar 2009
    Location
    Beech Hill - a village near Reading in the UK
    Posts
    2,812

    Default Re: RESTGen

    Frank - for Office365 I have, but this lets you do it for APIs I have never heard of, let alone built interfaces for.

    Mike

  5. #5
    Join Date
    Feb 2009
    Location
    Pine Island, Forida
    Posts
    2,076

    Default Re: RESTGen

    Makes sense.
    Frank Valcarcel
    Cove Systems, Inc.
    Pine Island, Florida USA
    fv@covesys.com
    (239) 823-7976

  6. #6
    Join Date
    Feb 2009
    Location
    Cayman Islands
    Posts
    3,969

    Default Re: RESTGen

    Quote Originally Posted by Mike Peat View Post
    ...

    Mike
    Mike,
    did you ever bring RESTGen into the 19.x versions?

    I'm able to get by with directly accessing the namescan.io JSON as I know the current structure, but thre's much of interest that I'm not showing yet and pulling everything would assist.
    I should be on a beach ...

  7. #7
    Join Date
    Mar 2009
    Location
    Beech Hill - a village near Reading in the UK
    Posts
    2,812

    Default Re: RESTGen

    Dave

    Yes, I did a 19.0 version for the Atlanta Synergy OAuth2 course.

    RESTGen 19.0 version (zipped): RestGen190.zip.

    I also find a 19.1 version (also zipped: RestGen191.zip. I suspect it only differs in the DF version... memory fails me.

    Mike

  8. #8
    Join Date
    Feb 2009
    Location
    Cayman Islands
    Posts
    3,969

    Default Re: RESTGen

    Quote Originally Posted by Mike Peat View Post
    Dave

    Yes, I did a 19.0 version for the Atlanta Synergy OAuth2 course.

    RESTGen 19.0 version (zipped): RestGen190.zip.

    I also find a 19.1 version (also zipped: RestGen191.zip. I suspect it only differs in the DF version... memory fails me.

    Mike
    Ah, it's probably on my laptop then. Thanks for the links.
    I should be on a beach ...

Tags for this Thread

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •