Skip to content

Commit

Permalink
Merge pull request #25 from radumg/dynwww-docs
Browse files Browse the repository at this point in the history 
Dynwww docs
  • Loading branch information
@radumg
radumg authored Aug 15, 2018
2 parents 2275e7f + 0dd3933 commit ba612a2
Showing 1 changed file with 66 additions and 63 deletions.
129 changes: 66 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,94 +3,66 @@
---
__DynaWeb__ is a [Dynamo](http://www.dynamobim.org) package providing support for interaction with the interwebz in general and with REST APIs in particular.

It's meant to provide building blocks so you can build Dynamo integrations with just about any web service out there. It helps you retrieve (GET) stuff from the web, send (POST) information to the web and everything in between (PUT, DELETE, PATCH, etc). The package also includes some rather nifty `deserialisation` nodes, so you can use the information you get from the web directly in Dynamo graphs, as native types.
### What does it do ?

![DynaWeb package screenshot](https://raw.githubusercontent.com/radumg/DynaWeb/master/samples/DynaWeb.png)

# Status : Beta
The package is in active development and is currently available as an open beta.

This stage is for intense feedback from you, testing it, so I would really like to know what cloud/web platforms you'd like to use Dynamo with and how.
Please see and add your comments to this [first issue](https://github.com/radumg/DynaWeb/issues/1) and feel free to [open more issues](https://github.com/radumg/DynaWeb/issues/new) with any ideas you might have.

## Repository notes
This public repository is only hosting the issues and in-progress builds of the package, accessible on the [releases page](https://github.com/radumg/DynaWeb/releases).
The repository is only private in the sense that source code is not made available and contributions are by invite-only. If you would like to contribute and help develop it, please open an issue requesting access to the `development repo` instead.
It helps you
- retrieve (GET) stuff from the web
- send (POST) information to the web
- everything in between (PUT, DELETE, PATCH, etc).
- the package also includes some rather nifty JSON `de/serialisation` nodes, so you can use the information you get from the web directly in Dynamo graphs, as native types.

*Note : I have every intention to open-source this eventually but would like to focus on testing and validating some of the underlying assumptions before making it available to the general audience. The ultimate goal is to see this merged back into the Dynamo Core library, to enable as many people to start interacting with the web more.*
![DynaWeb package screenshot](https://raw.githubusercontent.com/radumg/DynaWeb/master/samples/DynaWeb.png)

*I know all this is slightly different to how i usually do things (oss), but i wanted to test a few things out. Feedback is welcomed, as always.*
### How it came about

__DynaWeb__ was designed as a package to make other packages, so it provides building blocks enabling you to build Dynamo integrations with just about any web service out there. After making DynaSlack & DynAsana, it became clear that writing a ZeroTouch-based package for every web service I or the community would want to integrate with was simply not scalable or sustainable, no matter how much code was re-used. DynAsana is an abstracted DynaSlack and DynaWeb is an even more abstracted & modularised DynAsana.

# Getting Started

## Package manager
`DynaWeb` is now available on the Dynamo package manager, search for `DynaWeb` and install it.

## Manual install
If you prefer to install one of the more experimental/work-in-progress builds, you can still follow the instructions below.

- Download the latest release from the [Releases page](https://github.com/radumg/DynaWeb/releases)
- unzip the downloaded file
- once unzipped, copy the `DynaWeb` folder to the location of your Dynamo packages :
- `%appdata%\Dynamo\Dynamo Core\1.3\packages` for Dynamo Sandbox, replacing `1.3` with your version of Dynamo
- `%appdata%\Dynamo\Dynamo Revit\1.3\packages` for Dynamo for Revit, replacing `1.3` with your version of Dynamo
- start Dynamo, the package should now be listed as `DynWWW` in the library.

## Still can't see the package in Dynamo ?

This issue should be fixed now the package is distributed through the package manager, I definitely recommending getting it that way. However, in case you still have issues, see instructions below :

As [reported](https://github.com/radumg/DynaWeb/issues/10) by users, Windows sometimes blocks `.dll` files for security reasons. To resolve this, you'll have to go through the steps below for each assembly (`.dll` file) in the package :
1. Right-click on `.dll` file and select properties
2. Tick the `Unblock` checkbox at the bottom, in the Security section.
3. Launch Dynamo again, the package should now load.

![image](https://user-images.githubusercontent.com/15014799/29770289-3c13172a-8be6-11e7-983e-6fb3c71ad136.png)

## Updating from alpha-0.5 build ?
The changes in `1.0` are breaking, meaning graphs using the previous version will not work. However, instead of re-creating them, you can simply open the `.dyn` files using Notepad (though i recommend SublimeText) and perform the following text find/replaces :
- replace `DSCore.Web.` with `DynaWeb.`
- replace `DynWWW.dll` with `DynaWeb.dll`
- replace `WebClient.WebClient` with `WebClient.ByUrl`
`DynaWeb` is now available on the Dynamo package manager, search for `DynaWeb` and install it from there.
See [Alternative installation methods](#alternative-installation-methods) at the end of this document for alternative install methods.

# Using DynaWeb
Please consult the sample files provided in this repository and in the package's `extra` folder - they contain notes and instructions on how to use the nodes. I'm not providing extensive documentation on this page on purpose - to see how intuitive the design of the package & nodes is to first-time users.
This repository has quite a few sample files provided to help you get started with __DynaWeb__.

Feel free to submit PR if you want to add some documentation in the meantime.
I highly recommed starting with the samples as they contain detailed notes and instructions on how to use each of the nodes.
Feel free to open an issue or submit a PR if you'd like to see further some documentation added here.

## Samples
There are 8 sample Dynamo graphs included with the package, check out the `extra` folder in the downloaded package or the [samples folder](https://github.com/radumg/DynaWeb/tree/master/samples) of this repository. Also note the DYN samples are offered in both Dynamo 1.3 file format and Dynamo 2.0 new format.
There are 8 sample Dynamo graphs included with the package, provided in both Dynamo `1.3` XML file format and Dynamo `2.0`'s new JSON format.

You can find the samples in this repository's [`samples folder`](https://github.com/radumg/DynaWeb/tree/master/samples) folder, as well as and in the `extra` folder of the package you download using the Dynamo Package Manager, typically found here : `%appdata%\Dynamo\Dynamo Revit\1.3\packages\DynaWeb` (note version and Revit flavour of Dynamo, your location may vary).

The samples start from super-simple and increase in complexity :
The samples start from super-simple and progressively increase in complexity :

__Sample 1 - A first request__
#### Sample 1 - A first request
3 nodes, similar to out-of-the-box (OOTB) Dynamo experience today.

__Sample 2 - A simple request__
introduces the 3 stages of performing web requests and explains quite a few things. Also show how to achieve same thing with the OOTB node.
#### Sample 2 - A simple request
Introduces the 3 stages of performing web requests and explains quite a few things. Also show how to achieve same thing with the OOTB node.

__Sample 3 - Requst + benchmarking__
same as sample 2 but with added nodes that provide more information about the request (timing, etc) and output the results to text files.
#### Sample 3 - Requst + benchmarking
Same as sample 2 but with added nodes that provide more information about the request (timing, etc) and output the results to text files.

__Sample 4 - REST API example__
this introduces the use of the `WebClient` class and some of the basic priciples of interacting with REST services. Uses a REST API that is freely accessible and returns JSON reponses. Contrasts using a `WebClient` and a `WebRequest` to achieve same thing and also introduces `Deserialisation`.
#### Sample 4 - REST API example
This introduces the use of the `WebClient` class and some of the basic priciples of interacting with REST services. Uses a REST API that is freely accessible and returns JSON reponses. Contrasts using a `WebClient` and a `WebRequest` to achieve same thing and also introduces `Deserialisation`.

__Sample 5 - REST API advanced__
#### Sample 5 - REST API advanced
Introduces POST-ing to a REST API service and handling JSON payloads. Once the request is submitted, the response is deserialised too.

__Sample 6 - Complex POST request__
further expands on the above example, building a complex `WebRequest` with 6 steps before its execution.
#### Sample 6 - Complex POST request
Further expands on the above example, building a complex `WebRequest` with 6 steps before its execution.

__Sample 7 - Upload file to Autodesk Forge__
this example builds a `WebRequest` and attaches a file to it, to upload directly to the `Autodesk Forge` service. See the issue that sparked this sample [here](https://github.com/radumg/DynaWeb/issues/11).
#### Sample 7 - Autodesk Forge - Upload file
This example builds a `WebRequest` and attaches a file to it, to upload directly to the `Autodesk Forge` service. See the issue that sparked this sample [here](https://github.com/radumg/DynaWeb/issues/11).

__Sample 8 - Autodesk Forge request token__
this example builds a POST `WebRequest`, used to request an authorisation token from the `Autodesk Forge` service. See the issue that sparked this sample [here](https://github.com/radumg/DynaWeb/issues/13).
#### Sample 8 - Autodesk Forge - Request auth token
This example builds a POST `WebRequest`, used to request an authorisation token from the `Autodesk Forge` service. See the issue that sparked this sample [here](https://github.com/radumg/DynaWeb/issues/13).


## Class structure
There's 5 main namespaces you'll find in DynaWeb :
## Structure
There's 5 main components in DynaWeb :
- `WebRequest` : the web request that gets executed
- `WebClient` : the context in which a request is executed
- `WebResponse` : this contains the response from the server, as well as additional metadata about the response & server itself
Expand All @@ -100,7 +72,38 @@ There's 5 main namespaces you'll find in DynaWeb :
Simply put, use `WebRequest` nodes for one-off requests and start using a `WebClient` when you are interacting with REST APIs and/or have multiple request to similar endpoints/URLs.
When using a `WebClient`, the `WebRequest` is still what gets executed, but it allows you more control over how that occurs (custom timeouts, etc)

*Note : When executing a `WebRequest` on its own, the DynaWeb package constructs an empty `WebClient` in the background anyway as it's needed for execution.*
#### Fun facts
- when executing a `WebRequest` on its own, the DynaWeb package constructs an empty `WebClient` in the background anyway as it's needed for execution
- the strucuture of the source code shows up directly in Dynamo

## Alternative installation methods

### Manual install
If you prefer to install one of the more experimental/work-in-progress builds, you can still follow the instructions below.

- Download the latest release from the [Releases page](https://github.com/radumg/DynaWeb/releases)
- unzip the downloaded file
- once unzipped, copy the `DynaWeb` folder to the location of your Dynamo packages :
- `%appdata%\Dynamo\Dynamo Core\1.3\packages` for Dynamo Sandbox, replacing `1.3` with your version of Dynamo
- `%appdata%\Dynamo\Dynamo Revit\1.3\packages` for Dynamo for Revit, replacing `1.3` with your version of Dynamo
- start Dynamo, the package should now be listed as `DynWWW` in the library.

### Still can't see the package in Dynamo ?

This issue should be fixed now the package is distributed through the package manager, I definitely recommending getting it that way. However, in case you still have issues, see instructions below :

As [reported](https://github.com/radumg/DynaWeb/issues/10) by users, Windows sometimes blocks `.dll` files for security reasons. To resolve this, you'll have to go through the steps below for each assembly (`.dll` file) in the package :
1. Right-click on `.dll` file and select properties
2. Tick the `Unblock` checkbox at the bottom, in the Security section.
3. Launch Dynamo again, the package should now load.

![image](https://user-images.githubusercontent.com/15014799/29770289-3c13172a-8be6-11e7-983e-6fb3c71ad136.png)

### Updating from alpha-0.5 build ?
The changes in `1.0` are breaking, meaning graphs using the previous version will not work. However, instead of re-creating them, you can simply open the `.dyn` files using Notepad (though i recommend SublimeText) and perform the following text find/replaces :
- replace `DSCore.Web.` with `DynaWeb.`
- replace `DynWWW.dll` with `DynaWeb.dll`
- replace `WebClient.WebClient` with `WebClient.ByUrl`


## Prerequisites
Expand Down

0 comments on commit ba612a2

Please sign in to comment.