Skip to content

Commit e3b1a4b

Browse files
ahmadnassriahmadnassri
committed
more details in README and consistent naming of 'target' in place of 'language"
1 parent bd10060 commit e3b1a4b

3 files changed

Lines changed: 356 additions & 12 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Contributing to this project
2+
3+
Please take a moment to review this document in order to make the contribution
4+
process easy and effective for everyone involved.
5+
6+
Following these guidelines helps to communicate that you respect the time of
7+
the developers managing and developing this open source project. In return,
8+
they should reciprocate that respect in addressing your issue or assessing
9+
patches and features.
10+
11+
## Using the issue tracker
12+
13+
The [issue tracker](/issues) is the preferred channel for [bug reports](#bug-reports),
14+
[features requests](#feature-requests) and [submitting pull requests](#pull-requests),
15+
but please respect the following restrictions:
16+
17+
* Please **do not** use the issue tracker for personal support requests (use
18+
[Stack Overflow](http://stackoverflow.com) or IRC).
19+
20+
* Please **do not** derail or troll issues. Keep the discussion on topic and
21+
respect the opinions of others.
22+
23+
## Bug reports
24+
25+
A bug is a _demonstrable problem_ that is caused by the code in the repository.
26+
Good bug reports are extremely helpful - thank you!
27+
28+
Guidelines for bug reports:
29+
30+
1. **Use the GitHub issue search** — check if the issue has already been
31+
reported.
32+
33+
2. **Check if the issue has been fixed** — try to reproduce it using the
34+
latest `master` or development branch in the repository.
35+
36+
3. **Isolate the problem** — create a [reduced test
37+
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
38+
39+
A good bug report shouldn't leave others needing to chase you up for more
40+
information. Please try to be as detailed as possible in your report. What is
41+
your environment? What steps will reproduce the issue? What browser(s) and OS
42+
experience the problem? What would you expect to be the outcome? All these
43+
details will help people to fix any potential bugs.
44+
45+
Example:
46+
47+
> Short and descriptive example bug report title
48+
>
49+
> A summary of the issue and the browser/OS environment in which it occurs. If
50+
> suitable, include the steps required to reproduce the bug.
51+
>
52+
> 1. This is the first step
53+
> 2. This is the second step
54+
> 3. Further steps, etc.
55+
>
56+
> `<url>` - a link to the reduced test case
57+
>
58+
> Any other information you want to share that is relevant to the issue being
59+
> reported. This might include the lines of code that you have identified as
60+
> causing the bug, and potential solutions (and your opinions on their
61+
> merits).
62+
63+
## Feature requests
64+
65+
Feature requests are welcome. But take a moment to find out whether your idea
66+
fits with the scope and aims of the project. It's up to *you* to make a strong
67+
case to convince the project's developers of the merits of this feature. Please
68+
provide as much detail and context as possible.
69+
70+
## Pull requests
71+
72+
Good pull requests (patches, improvements, new features) are a fantastic
73+
help. They should remain focused in scope and avoid containing unrelated
74+
commits.
75+
76+
**Please ask first** before embarking on any significant pull request (e.g.
77+
implementing features, refactoring code, porting to a different language),
78+
otherwise you risk spending a lot of time working on something that the
79+
project's developers might not want to merge into the project.
80+
81+
Please adhere to the coding conventions used throughout a project (indentation,
82+
accurate comments, etc.) and any other requirements (such as test coverage).
83+
84+
Follow this process if you'd like your work considered for inclusion in the
85+
project:
86+
87+
1. [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork,
88+
and configure the remotes:
89+
90+
```bash
91+
# Clone your fork of the repo into the current directory
92+
git clone https://github.com/<your-username>/<repo-name>
93+
# Navigate to the newly cloned directory
94+
cd <repo-name>
95+
# Assign the original repo to a remote called "upstream"
96+
git remote add upstream https://github.com/ahmadnassri/httpsnippet.git
97+
```
98+
99+
2. If you cloned a while ago, get the latest changes from upstream:
100+
101+
```bash
102+
git checkout <dev-branch>
103+
git pull upstream <dev-branch>
104+
```
105+
106+
3. Create a new topic branch (off the main project development branch) to
107+
contain your feature, change, or fix:
108+
109+
```bash
110+
git checkout -b <topic-branch-name>
111+
```
112+
113+
4. Commit your changes in logical chunks. Please adhere to these [git commit
114+
message guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
115+
or your code is unlikely be merged into the main project. Use Git's
116+
[interactive rebase](https://help.github.com/articles/interactive-rebase)
117+
feature to tidy up your commits before making them public.
118+
119+
5. Locally merge (or rebase) the upstream development branch into your topic branch:
120+
121+
```bash
122+
git pull [--rebase] upstream <dev-branch>
123+
```
124+
125+
6. Push your topic branch up to your fork:
126+
127+
```bash
128+
git push origin <topic-branch-name>
129+
```
130+
131+
7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
132+
with a clear title and description.
133+
134+
**IMPORTANT**: By submitting a patch, you agree to allow the project owner to
135+
license your work under the same license as that used by the project.

‎README.md‎

Lines changed: 217 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,227 @@
1-
# HTTP Snippet
1+
# HTTP Snippet [![version][npm-version]][npm-url] [![License][npm-license]][license-url]
2+
3+
HTTP Request snippet generator for *most* languages.
4+
Relies on the popular [HAR](http://www.softwareishard.com/blog/har-12-spec/#request) format to import data and describe HTTP calls.
5+
6+
[![Build Status][travis-image]][travis-url]
7+
[![Downloads][npm-downloads]][npm-url]
8+
[![Code Climate][codeclimate-quality]][codeclimate-url]
9+
[![Coverage Status][codeclimate-coverage]][codeclimate-url]
10+
[![Dependencies][david-image]][david-url]
11+
12+
## Table of contents
13+
- [Targets](#Targets)
14+
- [Installation](#installation)
15+
- [Usage](#usage)
16+
- [Documentation](#documentation)
17+
- [Bugs and feature requests](#bugs-and-feature-requests)
18+
- [Contributing](#contributing)
19+
- [Versioning](#versioning)
20+
- [License](#license)
21+
22+
## Targets
23+
24+
currently the following output [targets](/src/targets) are supported:
25+
26+
- [cURL](http://curl.haxx.se/)
27+
- [HTTPie](http://httpie.org)
28+
- Node.js
29+
- [Native](http://nodejs.org/api/http.html#http_http_request_options_callback)
30+
- PHP
31+
- [ext-curl](http://php.net/manual/en/book.curl.php)
32+
- [Wget](https://www.gnu.org/software/wget/)
33+
34+
## Installation
35+
36+
install from source or through [npm](https://www.npmjs.com/):
237

338
```shell
4-
npm install -g httpsnippet
39+
# to use in cli
40+
npm install --global httpsnippet
41+
42+
# to use as a module
43+
npm install httpsnippet
544
```
645

746
## Usage
847

48+
### CLI
49+
50+
```
51+
Usage: httpsnippet [options] <file>
52+
53+
Options:
54+
55+
-h, --help output usage information
56+
-V, --version output the version number
57+
-t, --target <target> target output
58+
-o, --output <directory> write output to directory
59+
-n, --output-name <name> output file name
60+
```
61+
62+
#### Example
63+
64+
process single file:
65+
66+
```shell
67+
httpsnippet my-api-endpoint.json --langauge php --output ./snippets
68+
```
69+
970
```shell
10-
httpsnippet har.json --langauge PHP --output snippet.php
71+
tree snippets
72+
```
73+
74+
```
75+
snippets/
76+
└── my-api-endpoint.php
77+
```
78+
79+
process multiple files:
80+
81+
```shell
82+
httpsnippet /*.json --langauge nodejs --output ./snippets
83+
```
84+
85+
```shell
86+
tree sources/
87+
```
88+
89+
```
90+
sources/
91+
├── endpoint-1.json
92+
├── endpoint-2.json
93+
└── endpoint-3.json
94+
```
95+
96+
```shell
97+
tree snippets/
98+
```
99+
100+
```
101+
snippets/
102+
├── endpoint-1.js
103+
├── endpoint-2.js
104+
└── endpoint-3.js
11105
```
12106

13-
### Options
14107

15-
| Name | Description |
16-
| ------------ | ----------------------------------------- |
17-
| `--langauge` | |
18-
| `--output` | |
108+
### Module
109+
110+
```js
111+
var httpsnippet = require('httpsnippet');
112+
var snippet = new httpsnippet(source);
113+
114+
// generate cURL output
115+
console.log(snippet.curl({
116+
indent: ' ';
117+
}));
118+
119+
// generate nodeJS output
120+
snippet.nodejs();
121+
```
122+
123+
## Documentation
124+
125+
At the heart of this module is the [HAR Request object](http://www.softwareishard.com/blog/har-12-spec/#request) as the http request description format, please review some of the sample JSON HAR Request objects in [test fixtures](/test/fixtures), or read the [HAR Docs](http://www.softwareishard.com/blog/har-12-spec/#request) for more details.
126+
127+
### Output Targets
128+
129+
output [targets](/src/targets) are simple modules that expose a constructor *(which handles the transformation)* and a utility method `extname` *(used in CLI for writing output into disk)*
130+
131+
```js
132+
module.exports = function (opts) {
133+
// optionally process `opts` object for target specific configuration
134+
//
135+
// process `this.source` object
136+
//
137+
// return processed output as string
138+
};
139+
140+
module.exports.extname = function () {
141+
// return preferred filename extention
142+
};
143+
```
144+
145+
### Target Options
146+
147+
### cURL
148+
149+
| Option | Default | Description |
150+
| -------- | ------- | ------------------------------------------------------------------------ |
151+
| `short` | `false` | use short form of cURL CLI options |
152+
| `indent` | ` ` | line break & indent output value, set to `false` to disable line breaks |
153+
154+
### HTTPie
155+
156+
| Option | Default | Description |
157+
| --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
158+
| `body` | `false` | only the response body is printed |
159+
| `headers` | `false` | only the response headers are printed |
160+
| `verbose` | `false` | print the whole HTTP exchange (request and response) |
161+
| `print` | `false` | selects parts of the HTTP exchange, e.g. `--print=Hh` *(see [httpie docs](https://github.com/jakubroztocil/httpie#output-options))* |
162+
| `cert` | `false` | use a client side certificate *(see [httpie docs](https://github.com/jakubroztocil/httpie#client-side-ssl-certificate))* |
163+
| `verify` | `false` | server SSL certificate verification *(see [httpie docs](https://github.com/jakubroztocil/httpie#server-ssl-certificate-verification))* |
164+
| `pretty` | `false` | syntax highlighting *(see [httpie docs](https://github.com/jakubroztocil/httpie#colors-and-formatting))* |
165+
| `style` | `false` | syntax highlighting *(see [httpie docs](https://github.com/jakubroztocil/httpie#colors-and-formatting))* |
166+
| `timeout` | `false` | overwrite the default *30s* timeout |
167+
| `short` | `false` | use short form of cURL CLI options |
168+
| `indent` | ` ` | line break & indent output value, set to `false` to disable line breaks |
169+
170+
### Wget
171+
172+
| Option | Default | Description |
173+
| --------- | ------- | ------------------------------------------------------------------------ |
174+
| `short` | `false` | use short form of cURL CLI options |
175+
| `indent` | ` ` | line break & indent output value, set to `false` to disable line breaks |
176+
| `verbose` | `false` | by default, `--quiet` is always used, unless `verbose` is set to `true` |
177+
178+
## Bugs and feature requests
179+
180+
Have a bug or a feature request? Please first read the [issue guidelines](CONTRIBUTING.md#using-the-issue-tracker) and search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](/issues).
181+
182+
## Contributing
183+
184+
Please read through our [contributing guidelines](CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on development.
185+
186+
More over, if your pull request contains JavaScript patches or features, you must include relevant unit tests.
187+
188+
Editor preferences are available in the [editor config](.editorconfig) for easy use in common text editors. Read more and download plugins at <http://editorconfig.org>.
189+
190+
## Versioning
191+
192+
For transparency into our release cycle and in striving to maintain backward compatibility, this project is maintained under the Semantic Versioning guidelines. Sometimes we screw up, but we'll adhere to these rules whenever possible.
193+
194+
Releases will be numbered with the following format:
195+
196+
`<major>.<minor>.<patch>`
197+
198+
And constructed with the following guidelines:
199+
200+
- Breaking backward compatibility **bumps the major** while resetting minor and patch
201+
- New additions without breaking backward compatibility **bumps the minor** while resetting the patch
202+
- Bug fixes and misc changes **bumps only the patch**
203+
204+
For more information on SemVer, please visit <http://semver.org/>.
205+
206+
## License
207+
208+
Licensed under [The MIT License](LICENSE).
209+
210+
----
211+
212+
[license-url]: https://github.com/ahmadnassri/httpsnippet/blob/master/LICENSE
213+
214+
[travis-url]: https://travis-ci.org/ahmadnassri/httpsnippet
215+
[travis-image]: https://img.shields.io/travis/ahmadnassri/httpsnippet.svg?style=flat-square
216+
217+
[npm-url]: https://www.npmjs.com/package/httpsnippet
218+
[npm-license]: https://img.shields.io/npm/l/httpsnippet.svg?style=flat-square
219+
[npm-version]: https://img.shields.io/npm/v/httpsnippet.svg?style=flat-square
220+
[npm-downloads]: https://img.shields.io/npm/dm/httpsnippet.svg?style=flat-square
221+
222+
[codeclimate-url]: https://codeclimate.com/github/ahmadnassri/httpsnippet
223+
[codeclimate-quality]: https://img.shields.io/codeclimate/github/ahmadnassri/httpsnippet.svg?style=flat-square
224+
[codeclimate-coverage]: https://img.shields.io/codeclimate/coverage/github/ahmadnassri/httpsnippet.svg?style=flat-square
225+
226+
[david-url]: https://david-dm.org/ahmadnassri/httpsnippet
227+
[david-image]: https://img.shields.io/david/ahmadnassri/httpsnippet.svg?style=flat-square

0 commit comments

Comments
 (0)