Documentation

[SchlenkR]

• Multipart

[varora-aga]

Hello,

I am a web developer working in ASP.net applications but have never worked in F#.
Searching out document editing capabilities remotely, I found Webdav and FsHTTP as alternatives.

I was able to successfully build the project and dont know how to use it.
Can you please let me know if you have any detailed document about configuration and deployment in IIS?

I didn't know a place to communicate so posting comment on this issue item.

Thanks,
Varun

[SchlenkR]

FsHttp is no alternative to Asp.Net or any other content hosting / server side web framework. It’s a HTTP client library, that allows for sending HTTP requests to a web service.

[varora-aga]

Thanks for clarification.

I was working with MS Support guy and he recommended to go through this link and found FSHTTP reference there.
https://stackoverflow.com/questions/37276654/edit-in-word-using-wopi-and-office-online-server

Thanks.

Thanks,
Varun

[SchlenkR]

I doubt that the answer intentionally referenced FsHttp. Maybe it was a mistake and „sftp“ instead of „FsHttp“ was meant?

[FlippievanDyk]

I have only just started making use of the library, and the lack of multipart documentation lead to me almost dropping it. I assumed it simply wasn't supported.

Excited to give it a go, think I'll be making use of source as a reference, unless you have made a start on some branch?

This library is fantastic, thank you for all the effort!

[SchlenkR]

That would be really great, @FlippievanDyk - and thank you for the feedback. The documentation is something that definitely needs to be improved.

Here are some thoughts and hints:

• I ask myself if the structure of the documentation is too fine grained. Maybe it's better to merge some topics - what do you think?
• The current docu fucusses on explaining the DslCE style, but I find myself more often using the normal DSL style (also due to better intellisense support). As a first step for improvements, that's fine. In future releases, there might come some improvements for API of DSL style, too. Maybe it would be a good idea to provide examples in both styles side-by-side in the future (where it makes sense)?
• There are several docu TODOs in several places in the repo. They could be collected and evaluated if they still make sense or not, and work them out.

HowTo: Edit and build the documentation

• Editing: The source files for the docu are here
• Building: In the repo's root, use: dotnet fsi .\build.fsx docu

I really appreciate your help, and you can write here or DM me any time. Thank you very much!

[FlippievanDyk]

I've taken a closer look at the docs now, and I have a few thoughts on what could be done.

First two questions.

• It appears dotnet fsi .\build.fsx docu doesn't work. It only cleans the project. It doesn't make a difference Windows or WSL... running ./docu.ps1 does build the docs.
• The files in the reference sub-directory: I assume auto-generated, is that from the code? I am not so familiar with documentation tooling.
• And if they are auto generated, shouldn't the HTML files be removed and put in the .gitignore?

Then on to your hints:

• I ask myself if the structure of the documentation is too fine grained. Maybe it's better to merge some topics - what do you think?

I think I tend to agree with this statement. For example, there are separate get, get with cache-control and a post with a body. These could conceivably have been one, with a more detailed explanation. Perhaps it would be appropriate to have a general example, even if conceited, too show as much in one spot, with an explanation.

That could then be followed with a section for adding header, adding body, adding multipart form.

• The current docu fucusses on explaining the DslCE style, but I find myself more often using the normal DSL style (also due to better intellisense support). As a first step for improvements, that's fine. In future releases, there might come some improvements for API of DSL style, too. Maybe it would be a good idea to provide examples in both styles side-by-side in the future (where it makes sense)?

Again, I tend to agree. I have not used the Dsl style at all (partly due to lack of documentation, and I was slightly rushed). I think adding better docs for the DSL style would help. If you have working snippets, I would love to see one, just to show me in the right direction. Played around a bit just now, I think I understand it... Basically a fluent style?

• There are several docu TODOs in several places in the repo. They could be collected and evaluated if they still make sense or not, and work them out.

I have seen a TODO or two, but I must honest I've only skimmed the docs back to front, I haven't read everything yet. I think you are better qualified than I to say what is still relevant there.

What I've done so far:

I've only added this small section in Making Requests

(**
Here is an example of a POST with a multipart form:
*)
 
 http {
    POST "https://reqres.in/api/fileUplod"
    multipart
    filePart "proofOfPayment.pdf"
  }

I am not sure really where to document it more fully... I see in #86 that the Full APi reference is broken. Linking to that from where Header, Body and Multipart are explained would help a lot I think.

[SchlenkR]

For this library, my feeling is that having good examples should be the essential thing for a good documentation, since most of the used concepts are easy to understand. So let's focus on good examples.

To keep things simple, the current docu could be reworked:

• Extend it with more use case examples.
• Make important things like MultiPart and Configuration to appear more prominent using sub menu entries
• Restructuring

Structure
Here is a proposal for the structure of the docu with some comments:

• "Getting Started"
  The current "Making Requests" section could be the starting point for this topic. Put / move some simple examples here to show how the lib works for some common request / response use cases. It's the 80% one usually needs to know.
• "Request Body"
  • json / text / stream / setting ContentType explicitly
  • formUrlEncoded
  • File Upload
  • Multipart (see tests)
• Sending (async, lazy, etc.)
• Response Handling
  Add some expect and assert examples (see: Response.fs, l. 125ff)
• Configuration
  For each config method, there could be a simple example that explains the behaviour.
  • Basic configurations
  • HttpClient and HttpMessage
• F# Interactive
  Add % operator (see: Operators.fs) - which should only be recommended for FSI usage
• Advanced contepts
  • Builder types
  • Pre-configuring Builders
  • Naming Conventions
  • dispose behaviour somewhere

Hints

• The tests are a source to look at for important use cases.
• Alternative Styles: To keep things simple, the docu could be based on DslCE style for now, and an additional section explains alternatives:

http {
    POST "https://reqres.in/api/users"
    CacheControl "no-cache"
    body
}

post "https://reqres.in/api/users" {
    CacheControl "no-cache"
    body
}

Http.post "https://reqres.in/api/users"
|> Header.cacheControl "no-cache"
|> Request.send
|> Response.toJson

[FlippievanDyk]

I'm sorry I have taken so long to respond, had a bunch on my plate after hours, so haven't had a real chance to look at this.

I should have time this weekend to at least make a start. Anything I say further now won't be well thought out, so I'll rather not. Just wanted to let you know I haven't forgotten

[SchlenkR]

There's no need for making pressure; you can always decide ad hoc what / if you want to do something - that's no problem... I also started with some smaller docu things, but didn't commit them yet. I try to commit them this evening and comment here and let you know :)