3 ms·

Going slightly off tangent to ask about something. I often find myself in a situation when testing API to request for "API request and API response", including

Going slightly off tangent to ask about something. I often find myself in a situation when testing API to request for "API request and API response", including header, body, etc, the full complete information. This helps to identify any issue with it, and keep the full record for the future reference (it happens a lot that I need some information on the old API behavior weeks later). There seems to be lack of a single word in English to describe this except the long phrase above. Anyone has good suggestion? It goes without saying that this is a hard requirement I have for any API client but sadly most ones I tried always lack some information somewhere.

sureglymop 3y ago
In this case I recommend capturing your whole traffic for an endpoint, e.g. with MITMProxy as you are doing your requests. Often I test SPAs and do so by turning on MITMProxy with some filtering, using the app in the browser normally and then saving the traffic capture. Later I can even generate API docs from that. Regarding terminology, I'm also not sure how you'd describe that.
- paradite 3y ago
  Yes. I usually use MITMProxy for mobile and Chrome for desktop for such tasks. The other comment suggests the term "exchange" which I like.
jkbr 3y ago
> There seems to be lack of a single word in English to describe this except the long phrase above. Anyone has good suggestion? If you mean the request and response message pair, we call it "exchange" [0]. > It goes without saying that this is a hard requirement I have for any API client but sadly most ones I tried always lack some information somewhere. Both HTTPie Desktop and HTTPie CLI allow you to see the entire exchange. In the CLI, you can use the --verbose flag [0]. In the desktop app, there’s a “Request” tab. They both also support previewing the request without sending it. The CLI has --offline [1], and the Desktop has a live preview feature [2]. [0] https://httpie.io/docs/cli/what-parts-of-the-http-exchange-should-be-printed https://httpie.io/docs/cli/what-parts-of-the-http-exchange-s... [1] https://httpie.io/docs/cli/offline-mode https://httpie.io/docs/cli/offline-mode [2] https://raw.githubusercontent.com/httpie/desktop/master/.github/httpie-desktop.png https://raw.githubusercontent.com/httpie/desktop/master/.git...
- paradite 3y ago
  Thanks for the response. Does the client (desktop app) support exporting the full exchange as txt? I would switch to HTTPie Desktop if this is supported.
  - jkbr 3y ago
    We show the request/response in two separate panes, each with a menu offering Copy and Download actions. So it’s possible; it’s just a matter of multiple clicks. The desktop app also allows you to copy a corresponding HTTPie CLI command, which you can then enrich with --verbose, run in the terminal, and more easily copy the whole exchange output.
    - paradite 3y ago
      Thanks. So it is the same amount of steps as I have for Chrome now. Please do consider adding a feature to export everything in one shot. It would save people like me a lot of clicks (for a lot of APIs across different environments).
      - jkbr 3y ago
        It’s a good idea — we’ll look into making it as simple as in HTTPie CLI. Thanks for the feedback.
markoph 3y ago
The last thing that scratched this itch for me was Dredd https://github.com/apiaryio/dredd https://github.com/apiaryio/dredd . But writing tests in markdown is not for everyone. Here are few examples of what "test files" look like https://github.com/apiaryio/api-blueprint/tree/master/examples https://github.com/apiaryio/api-blueprint/tree/master/exampl... I didn't use in for two years so I can't say how well it works today (it doesn't appear to be actively maintained).
cdogl 3y ago
FWIW, I’m fond of a testing technique where the entire “exchange” of a request/response for a HTTP handler test case is committed to the repo. If the result doesn’t match what’s in the file, the test fails. You can run the tests with a special flag to update them in place. It gives great regression coverage on that edge of the system and it can easily be done with a good language HTTP library.
derefr 3y ago
I've seen "HTTP transcript" used in this sense. Rather than a general term, though, what you probably want to focus on — especially because you want to "keep a record" — is the common file format used for these: https://en.wikipedia.org/wiki/HAR_(file_format) https://en.wikipedia.org/wiki/HAR_(file_format) (It was created and initially supported by web browsers, but many CLI/GUI dev tools should be capable of emitting HARs as well, often "off to the side" in some logging directory while also presenting separate, pretty info on stdout.)
- paradite 3y ago
  The problem with HAR file is that it is by definition an archive format, and not design to be human-readable. For these types of records you typically want to store them in internal documentation system which usually consist of markdown or rich text documents for ease of browsing. Saving it as an attachment is possible, but it would require whoever that is reading it to download and view it inside a HAR viewer (Chrome), a few extra steps.

sureglymop 3y ago

In this case I recommend capturing your whole traffic for an endpoint, e.g. with MITMProxy as you are doing your requests. Often I test SPAs and do so by turning on MITMProxy with some filtering, using the app in the browser normally and then saving the traffic capture. Later I can even generate API docs from that. Regarding terminology, I'm also not sure how you'd describe that.

paradite 3y ago
Yes. I usually use MITMProxy for mobile and Chrome for desktop for such tasks. The other comment suggests the term "exchange" which I like.

jkbr 3y ago

> There seems to be lack of a single word in English to describe this except the long phrase above. Anyone has good suggestion? If you mean the request and response message pair, we call it "exchange" [0]. > It goes without saying that this is a hard requirement I have for any API client but sadly most ones I tried always lack some information somewhere. Both HTTPie Desktop and HTTPie CLI allow you to see the entire exchange. In the CLI, you can use the --verbose flag [0]. In the desktop app, there’s a “Request” tab. They both also support previewing the request without sending it. The CLI has --offline [1], and the Desktop has a live preview feature [2]. [0] https://httpie.io/docs/cli/what-parts-of-the-http-exchange-should-be-printed https://httpie.io/docs/cli/what-parts-of-the-http-exchange-s... [1] https://httpie.io/docs/cli/offline-mode https://httpie.io/docs/cli/offline-mode [2] https://raw.githubusercontent.com/httpie/desktop/master/.github/httpie-desktop.png https://raw.githubusercontent.com/httpie/desktop/master/.git...

paradite 3y ago
Thanks for the response. Does the client (desktop app) support exporting the full exchange as txt? I would switch to HTTPie Desktop if this is supported.
- jkbr 3y ago
  We show the request/response in two separate panes, each with a menu offering Copy and Download actions. So it’s possible; it’s just a matter of multiple clicks. The desktop app also allows you to copy a corresponding HTTPie CLI command, which you can then enrich with --verbose, run in the terminal, and more easily copy the whole exchange output.
  - paradite 3y ago
    Thanks. So it is the same amount of steps as I have for Chrome now. Please do consider adding a feature to export everything in one shot. It would save people like me a lot of clicks (for a lot of APIs across different environments).
    - jkbr 3y ago
      It’s a good idea — we’ll look into making it as simple as in HTTPie CLI. Thanks for the feedback.

markoph 3y ago

The last thing that scratched this itch for me was Dredd https://github.com/apiaryio/dredd https://github.com/apiaryio/dredd . But writing tests in markdown is not for everyone. Here are few examples of what "test files" look like https://github.com/apiaryio/api-blueprint/tree/master/examples https://github.com/apiaryio/api-blueprint/tree/master/exampl... I didn't use in for two years so I can't say how well it works today (it doesn't appear to be actively maintained).

cdogl 3y ago

FWIW, I’m fond of a testing technique where the entire “exchange” of a request/response for a HTTP handler test case is committed to the repo. If the result doesn’t match what’s in the file, the test fails. You can run the tests with a special flag to update them in place. It gives great regression coverage on that edge of the system and it can easily be done with a good language HTTP library.

derefr 3y ago

I've seen "HTTP transcript" used in this sense. Rather than a general term, though, what you probably want to focus on — especially because you want to "keep a record" — is the common file format used for these: https://en.wikipedia.org/wiki/HAR_(file_format) https://en.wikipedia.org/wiki/HAR_(file_format) (It was created and initially supported by web browsers, but many CLI/GUI dev tools should be capable of emitting HARs as well, often "off to the side" in some logging directory while also presenting separate, pretty info on stdout.)

paradite 3y ago
The problem with HAR file is that it is by definition an archive format, and not design to be human-readable. For these types of records you typically want to store them in internal documentation system which usually consist of markdown or rich text documents for ease of browsing. Saving it as an attachment is possible, but it would require whoever that is reading it to download and view it inside a HAR viewer (Chrome), a few extra steps.