Skip to content

Commit 71a9f92

Browse files
dblockdblock
authored
Merge pull request #39 from duffn/duffn/examples
Complete and organize README examples
2 parents 3ba2acf + 54d51a5 commit 71a9f92

File tree

1 file changed

+183
-31
lines changed

1 file changed

+183
-31
lines changed

‎README.md

+183-31
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,11 @@
11
Grape API on Rack
22
=================
33

4-
[![Test](https://github.com/grape/grape-on-rack/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/grape/grape-on-rack/actions/workflows/test.yml)
4+
[![Test](https://github.com/ruby-grape/grape-on-rack/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/ruby-grape/grape-on-rack/actions/workflows/test.yml)
55
[![Code Climate](https://codeclimate.com/github/ruby-grape/grape-on-rack.svg)](https://codeclimate.com/github/ruby-grape/grape-on-rack)
66

77
A [Grape](http://github.com/ruby-grape/grape) API mounted on Rack.
88

9-
* [ping](api/ping.rb): a hello world example that returns a JSON document
10-
* [post_put](api/post_put.rb): a simple `POST` and `PUT` example
11-
* [post_json](api/post_json.rb): an example that shows a `POST` of JSON data
12-
* [get_json](api/get_json.rb): an example that pre-processes params sent as JSON data
13-
* [rescue_from](api/rescue_from.rb): an example of `rescue_from` that wraps all exceptions in an HTTP error code 500
14-
* [path_versioning](api/path_versioning.rb): an example that uses path-based versioning
15-
* [header_versioning](api/header_versioning.rb): an example that uses vendor header-based versioning
16-
* [wrap_response](api/wrap_response.rb): a middleware that wraps all responses and always returns HTTP code 200
17-
* [content_type](api/content_type.rb): an example that overrides the default `Content-Type` or returns data in both JSON and XML formats
18-
* [upload_file](api/upload_file.rb): an example that demonstrates a file upload and download
19-
* [entites](api/entities.rb): an example of using [grape-entity](https://github.com/ruby-grape/grape-entity)
20-
* [headers](api/headers.rb): demonstrates header case-sensitive handling
21-
22-
See
23-
---
24-
25-
There's a deployed [grape-on-rack on Heroku](http://grape-on-rack.herokuapp.com/).
26-
279
Run
2810
---
2911

@@ -37,50 +19,220 @@ Loading NewRelic in developer mode ...
3719
[2013-06-20 08:57:58] INFO WEBrick::HTTPServer#start: pid=247 port=9292
3820
```
3921

40-
### Hello World
22+
List Routes
23+
-----------
24+
25+
```
26+
rake routes
27+
```
4128

42-
Navigate to http://localhost:9292/api/ping with a browser or use `curl`.
29+
Explore the API
30+
---------------
31+
32+
Explore the API using [Swagger UI](http://petstore.swagger.io). Run the application and point the explorer to `http://localhost:9292/api/swagger_doc` or `http://grape-on-rack.herokuapp.com/api/swagger_doc`.
33+
34+
35+
## Examples
36+
### [ping](api/ping.rb)
37+
38+
A hello world example that returns a JSON document.
4339

4440
```
4541
$ curl http://localhost:9292/api/ping
4642
4743
{"ping":"pong"}
4844
```
4945

50-
### Get Plain Text
46+
### [post_put](api/post_put.rb)
47+
48+
A simple `POST` and `PUT` example.
49+
50+
```
51+
curl -XPOST -d '' http://localhost:9292/api/ring
52+
53+
{"rang":7}
54+
```
55+
56+
```
57+
curl -XPUT -d '{"count":2}' -H "Content-Type:application/json" http://localhost:9292/api/ring
58+
59+
{"rang":9}
60+
```
61+
62+
### [post_json](api/post_json.rb)
63+
64+
An example that shows a `POST` of JSON data.
65+
66+
```
67+
$ curl -XPOST http://localhost:9292/api/spline -d '{"reticulated":"lots"}' -H "Content-Type:application/json"
68+
69+
{"reticulated":"lots"}
70+
```
71+
72+
### [get_json](api/get_json.rb)
73+
74+
An example that pre-processes params sent as JSON data.
75+
76+
```
77+
$ curl http://localhost:9292/api/reticulated_splines?splines=[{"id":1,"reticulated":true},{"id":2,"reticulated":false}]
78+
79+
[{"id":1,"reticulated":false},{"id":2,"reticulated":true}]
80+
```
81+
82+
### [rescue_from](api/rescue_from.rb)
83+
84+
An example of `rescue_from` that wraps all exceptions in an HTTP error code 500.
85+
86+
```
87+
$ curl -i http://localhost:9292/api/raise
88+
HTTP/1.1 500 Internal Server Error
89+
Last-Modified: Wed, 15 Jun 2022 01:12:37 GMT
90+
Content-Type: text/html
91+
Content-Length: 234
92+
Vary: Origin
93+
Server: WEBrick/1.4.2 (Ruby/2.6.5/2019-10-01)
94+
Date: Sat, 18 Jun 2022 01:51:25 GMT
95+
Connection: Keep-Alive
96+
97+
<html>
98+
<head>
99+
<title>Unexpected Error</title>
100+
</head>
101+
<body>
102+
<h1>Ouch...</h1>
103+
<a href="http://rack.rubyforge.org/">
104+
<img src="/images/rack-logo.png">
105+
</a>
106+
<p>
107+
Something went terribly wrong.
108+
</p>
109+
</body>
110+
</html>
111+
```
112+
113+
### [path_versioning](api/path_versioning.rb)
114+
115+
An example that uses path-based versioning.
116+
117+
```
118+
$ curl http://localhost:9292/api/vendor
119+
120+
{"path":"acme"}
121+
```
122+
123+
### [header_versioning](api/header_versioning.rb)
124+
125+
An example that uses vendor header-based versioning.
126+
127+
```
128+
$ curl -H "Accept:application/vnd.acme-v1+json" http://localhost:9292/api
129+
130+
{"header":"acme"}
131+
```
132+
### [wrap_response](api/wrap_response.rb)
133+
134+
A middleware that wraps all responses and always returns HTTP code 200.
135+
136+
```
137+
$ curl http://localhost:9292/api/decorated/ping
138+
139+
{"body":{"ping":"pong"},"status":200}
140+
```
141+
142+
### [content_type](api/content_type.rb)
143+
144+
An example that overrides the default `Content-Type` or returns data in both JSON and XML formats.
51145

52146
```
53147
$ curl http://localhost:9292/api/plain_text
54148
55149
A red brown fox jumped over the road.
56150
```
57151

58-
### Upload a File
152+
```
153+
$ curl http://localhost:9292/api/mixed
154+
155+
{"data":"A red brown fox jumped over the road."}
156+
```
157+
158+
```
159+
$ curl http://localhost:9292/api/mixed.xml
160+
161+
<?xml version="1.0" encoding="UTF-8"?>
162+
<hash>
163+
<data>A red brown fox jumped over the road.</data>
164+
</hash>
165+
```
166+
167+
### [upload_file](api/upload_file.rb)
168+
169+
An example that demonstrates a file upload and download.
59170

60171
```
61172
$ curl -X POST -i -F image_file=@spec/fixtures/grape_logo.png http://localhost:9292/api/avatar
62173
63174
{"filename":"grape_logo.png","size":4272}
64175
```
65176

66-
### Upload and Download a File
67-
68177
```
69178
$ curl -X POST -i -F file=@spec/fixtures/grape_logo.png http://localhost:9292/api/download.png
179+
180+
HTTP/1.1 201 Created
181+
Content-Type: image/png
182+
Content-Disposition: attachment; filename*=UTF-8''grape_logo.png
183+
Vary: Origin
184+
Content-Length: 4272
185+
Server: WEBrick/1.4.2 (Ruby/2.6.5/2019-10-01)
186+
Date: Sat, 18 Jun 2022 02:12:21 GMT
187+
Connection: Keep-Alive
188+
```
189+
190+
```
70191
$ curl -X POST -i -F file=@api/ping.rb http://localhost:9292/api/download.rb
192+
193+
HTTP/1.1 201 Created
194+
Content-Type: application/x-ruby
195+
Content-Disposition: attachment; filename*=UTF-8''ping.rb
196+
Vary: Origin
197+
Content-Length: 115
198+
Server: WEBrick/1.4.2 (Ruby/2.6.5/2019-10-01)
199+
Date: Sat, 18 Jun 2022 02:12:47 GMT
200+
Connection: Keep-Alive
201+
202+
module Acme
203+
class Ping < Grape::API
204+
format :json
205+
get '/ping' do
206+
{ ping: 'pong' }
207+
end
208+
end
209+
end
71210
```
72211

73-
List Routes
74-
-----------
212+
### [entites](api/entities.rb)
213+
214+
An example of using [grape-entity](https://github.com/ruby-grape/grape-entity).
75215

76216
```
77-
rake routes
217+
$ curl http://localhost:9292/api/entities/1
218+
219+
{"tool":{"id":"1","length":10,"weight":"20kg"}}
78220
```
79221

80-
Explore the API
81-
---------------
222+
### [headers](api/headers.rb)
82223

83-
Explore the API using [Swagger UI](http://petstore.swagger.io). Run the application and point the explorer to `http://localhost:9292/api/swagger_doc` or `http://grape-on-rack.herokuapp.com/api/swagger_doc`.
224+
Demonstrates header case-sensitive handling.
225+
226+
```
227+
$ curl http://localhost:9292/api/headers/Host
228+
229+
{"Host":"localhost:9292"}
230+
```
231+
232+
See Also
233+
--------
234+
235+
There's a deployed [grape-on-rack on Heroku](http://grape-on-rack.herokuapp.com/).
84236

85237
New Relic
86238
---------

0 commit comments

Comments
 (0)