Using the REST Library: Difference between revisions
m
Changing where to get the library
(Creating (splitting up original article)) |
m (Changing where to get the library) |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
The simple example of a [[RESTful Service Theory|RESTful service]] set out in the article [[A Simple RESTful Service]] involved quite a bit of work to produce an API for only one table. | The simple example of a [[RESTful Service Theory|RESTful service]] set out in the article [[A Simple RESTful Service]] involved quite a bit of work to produce an API for only one table. | ||
An alternative approach is to use the REST library I ([[user:mikepeat|Mike]]) have created, which can be downloaded from [[File:RESTLibrary.zip]]. | An alternative approach is to use the REST library I ([[user:mikepeat|Mike]]) have created, which can be downloaded from <s>[[File:RESTLibrary.zip]]</s> (that one now obsolete) [https://github.com/DataFlexCode/UIG-REST-Library here] on [https://github.com/DataFlexCode GitHub/DataFlexCode]. | ||
To use it, unzip that file into some directory, then, from the workspace you are developing in, use that as a library; in the Studio do: Tools --> Maintain Libraries... --> Add Library, then navigate to where you unzipped it and within it select the "RESTLibrary.sws" file. | To use it, <s>unzip that file</s> download it (via a Git "pull" request) into some directory, then, from the workspace you are developing in, use that as a library; in the Studio do: Tools --> Maintain Libraries... --> Add Library, then navigate to where you <s>unzipped</s> downloaded it and within it select the "RESTLibrary.sws" file. | ||
That will add a new section to the Studio's Class Palette entitled "REST". | That will add a new section to the Studio's Class Palette entitled "REST". | ||
| Line 11: | Line 11: | ||
Then again do: File --> New --> Other --> DataFlex Source File, this time naming it '''ApiCustomersHandler'''. Into that blank file drag an object of the cRestResourceHandler class. Change the object's name to oApiCustomersHandler and set its psInterfacePath property (an empty string by default) to "'''customers'''". | Then again do: File --> New --> Other --> DataFlex Source File, this time naming it '''ApiCustomersHandler'''. Into that blank file drag an object of the cRestResourceHandler class. Change the object's name to oApiCustomersHandler and set its psInterfacePath property (an empty string by default) to "'''customers'''". | ||
Then in the DDO Explorer pane (lower-right in the Studio by default) click the "+" book icon (Add DDO) and select the cCustomerDataDictionary. | Then in the DDO Explorer pane (lower-right in the Studio by default) click the "<font color="green">+</font>" book icon (Add DDO: [[File:Add DD.jpg|15px]]) and select the cCustomerDataDictionary. | ||
Drag a cRESTApiObject from the class palette to below the comment "''Add your cRESTApiObjects here''". Rename it to "oCustomers". Set its phoDD property to oCustomer_DD, its psCollName (collection name) property to "'''customers'''" (plural) and its psInstName (instance name) property to "'''customer'''" (singular). | Drag a cRESTApiObject from the class palette to below the comment "''Add your cRESTApiObjects here''". Rename it to "oCustomers". Set its phoDD property to oCustomer_DD, its psCollName (collection name) property to "'''customers'''" (plural) and its psInstName (instance name) property to "'''customer'''" (singular). | ||
| Line 25: | Line 25: | ||
That should leave you with (some additional comments are mine): | That should leave you with (some additional comments are mine): | ||
WebOrderAPI.pkg: | '''WebOrderAPI.pkg''': | ||
<source lang="vdf"> | <source lang="vdf"> | ||
Use cRESTfulService.pkg | Use cRESTfulService.pkg | ||
| Line 72: | Line 72: | ||
</source> | </source> | ||
APICustomersHandler.pkg: | '''APICustomersHandler.pkg''': | ||
<source lang="vdf"> | <source lang="vdf"> | ||
Use cRESTResourceHandler.pkg | Use cRESTResourceHandler.pkg | ||
| Line 114: | Line 114: | ||
</source> | </source> | ||
Now you can immediately see the saving: 81 lines (most of which were written for you and a couple of which are comments I have added for clarification) vs. the 574 lines in the [[A Simple RESTful Service|Simple]] example, while most of the functionality is essentially the same (a careful examination | Now you can immediately see the saving: 81 lines (most of which were written for you and a couple of which are comments I have added for clarification) vs. the 574 lines in the [[A Simple RESTful Service|Simple]] example, while most of the functionality is essentially the same (a careful examination will reveal a bit more "[https://en.wikipedia.org/wiki/HATEOAS ''HATEOAS'']"-type information in some of the returned JSON in the former). | ||
In addition this approach has much more generality and extensibility: additional cRESTApiObjects | In addition, this approach has much more generality and extensibility: additional cRESTApiObjects, and the corresponding DDOs, can be added to the cApiCustomersHandler to provide for dependant sub-collections (since customers have orders, and orders have details), while other cRESTResourceHandler objects can be added to handle other top-level collections (orders, vendors, inventory, salespeople and so on). | ||
The library (in the cRESTApiObjects) provides mechanisms to exclude specific fields from the interface (Send AddExcludeColumn ''Table.Column''), or mark them as read-only through it (Send AddReadOnlyColumn ''Table.Column''), include parent columns in collections or instances (through the AddListColumn and AddInstanceColumn procedures) and even provide calculated pseudo-columns (AddListFunctionColumn and AddInstanceFunctionColumn). Entire collections can be set as read-only (pbReadOnly), no-update (pbNoUpdate) or no-delete (pbNoDelete). | The library (in the cRESTApiObjects) provides mechanisms to exclude specific fields from the interface (Send AddExcludeColumn ''Table.Column''), or mark them as read-only through it (Send AddReadOnlyColumn ''Table.Column''), include parent columns in collections or instances (through the AddListColumn and AddInstanceColumn procedures) and even provide calculated pseudo-columns (AddListFunctionColumn and AddInstanceFunctionColumn). Entire collections can be set as read-only (pbReadOnly), no-update (pbNoUpdate) or no-delete (pbNoDelete). | ||
In your browser, or testing tool such as [https://www.getpostman.com/ Postman] or the DataFlex [[ | In your browser, or testing tool such as [https://www.getpostman.com/ Postman] or the DataFlex [[Consuming RESTful Services in DataFlex|RESTTest view]] in another article in this series, you can access this one as ".../api/v1" (or just ".../api" if you didn't make the versioning change to the psPath setting). | ||
====Security==== | ====Security==== | ||
| Line 155: | Line 155: | ||
Move (Trim(WebAppUser.Password) = Trim(tCreds.sPassword)) to bOK | Move (Trim(WebAppUser.Password) = Trim(tCreds.sPassword)) to bOK | ||
</source> | </source> | ||
Which assumes that you are not using encrypted | Which assumes that you are not using encrypted passwords, however how to handle those is left as an exercise for the reader! | ||
Then at the top of the file add "'''Open WebAppUser'''", while at the top of the oWebOrderAPI object add "'''Property String psUsername'''". | Then at the top of the file add "'''Open WebAppUser'''", while at the top of the oWebOrderAPI object add "'''Property String psUsername'''". | ||
| Line 171: | Line 171: | ||
==See also== | ==See also== | ||
*[[REST]] | |||
*[[RESTful Service Theory]] | *[[RESTful Service Theory]] | ||
*[[RESTful Services in DataFlex]] | *[[RESTful Services in DataFlex]] | ||
| Line 176: | Line 177: | ||
*[[Creating RESTful Services in DataFlex]] | *[[Creating RESTful Services in DataFlex]] | ||
*[[A Simple RESTful Service]] | *[[A Simple RESTful Service]] | ||
* https://github.com/DataFlexCode/UIG-REST-Library | |||
[[Category:REST]] | [[Category:REST]][[Category:Web Services]] | ||