-
Notifications
You must be signed in to change notification settings - Fork 25
/
apiary.apib
1274 lines (944 loc) · 48.6 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
HOST: http://os-dev-gateway.nebo15.com:8080/
# Annon API Gateway
Annon is a configurable API gateway that acts as a reverse proxy with a plugin system. Plugins are reducing boilerplate that must be done in each service, making overall development faster. Also it stores all requests, responses and key metrics, making it easy to debug your application. Inspired by [Kong](https://getkong.org/).
It's free. Source code is available on [GitHub](https://github.com/Nebo15/annon.api).
> "Annon" translates from the Sindarin word for 'Great Door or Gate'. Sindarin is one of the many languages spoken by the immortal Elves.
Annon consist of multiple main parts:
- [Annon API Gateway](https://github.com/Nebo15/annon.api).
- [Annon Dashboard](https://github.com/Nebo15/annon.web) - UI that allows to manage Annon settings, review and analyze Requests.
- [Annon Status Pages](https://github.com/Nebo15/annon.status.web) - UI that renders APIs status pages;
- [EView](https://hex.pm/packages/eview) - hex package that allows to receive and modify client responses from Elixir application to match [Nebo #15 API Manifest](http://docs.apimanifest.apiary.io/). So your back-ends will respond in a same way as Annon does.
- [Mithril](https://github.com/Nebo15/mithril.api) - authentication and role management service.
## Goals of the Project
- Provide single easy to use API management system for medium-to-large scale applications.
- Reduce amount of work needed in other components by orchestrating common functionalities.
- Monitoring - control response time and get answer "what happened" even in a single request perspective. Provide data for in-depth analysis.
- Authorization - set authentication and authorization requirements for each resource and reject requests that do not satisfy them.
- Improve platform scalability.
## General Features
### Caching and Performance
For performance issues Annon has build-in cache manager, it will load data from DB only once, all further work will be based on this cached data.
Whenever a single node receives request that changes cached data, it's responsible to notify all other nodes in cluster about change, and they should reload configurations from DB.
Whenever new node joins to a cluster, all other nodes should drop their cache, to resolve consistency issues.
This feature is done via [skycluster](https://github.com/Nebo15/skycluster) package. All gateway nodes is connected via Erlang distribution protocol.
It support different discovery strategies:
- `kubernetes` - selecting pods via Kubernetes API;
- `gossip` - multicast UDP gossip, using a configurable port/multicast address;
- `epmd` - using standart Erlang Port Mapper Daemon.
### Request ID's
When receiving request gateway will generate unique `request_id`. It is used to log request and this request is sent to all upstream, so whole back-ends that is affected by a request will create logs with same request id's.
Optionally, you can send `X-Request-ID` header with your own request id, but you need to make sure that its length not less than 20 characters. Also, if should be unique, or you will receive error response.
### Request Logger
Annon stores all requests and responses by their unique Request ID's in a Cassandra database. You use this information to query requests and get base analytics via [Requests API](#reference/requests/collection/get-all-requests).
API consumers may provide a custom request ID by sending `X-Request-ID: <request_id>` header. Thus, your Front-End and upstream back-ends can log information with a single unique ID.
Also, idempotency plug is relying on this logs to provide idempotency guarantees for requests with same `X-Idempotency-Key: <idempotency_key>` headers.
### Monitoring
To monitor services status we will use DogStatsD integration, that will receive following metrics:
- `request.count` (counter) - [API](#reference/apis) hit rate.
- `request.size` (gauge) - HTTP `Content-Length ` request size.
- `responses.count` (counter) - same as `request.count` but sent after request dispatch and additionally tagged with `http.status`.
- `latencies.{client,gateway,upstream}` (gauge) - total request latency for a API consumer, additionally tagged with `http.status`.
All metrics have tags: `http.host`, `http.port`, `http.method`, `api.name` and `api.id` (if matches any), `request.id`. This allows to set different aggregated views on counter data.
We recommend you to try [DataDog](https://www.datadoghq.com/) for collecting and displaying performance metrics. But this is not a hard constraint, instead you can use any StatsD collector.
### Requests Idempotency
Annon guarantees that replayed requests with same `X-Idempotency-Key: <key>` and same request will get permanent response. This is useful in a financial application, where you need good protection from duplicate user actions.
### Requests Tracing
Annon supports [OpenTracing](http://opentracing.io/) in Erlang via [Otter](https://github.com/Bluehouse-Technology/otter) library. This means that by implementing OpenTracing API in other services you can trace complete request impact for each of your services.
### Management UI
## Installation
Annon can be installed by compiling it from sources, but we recommend you to use our pre-build Docker containers:
- [Annon API Gateway](https://hub.docker.com/r/nebo15/annon_api/);
- [Annon Dashboard](https://hub.docker.com/r/nebo15/annon.web/);
- [Annon Status Pages](https://hub.docker.com/r/nebo15/annon.status.web/);
- [Cassandra](https://hub.docker.com/r/nebo15/alpine-cassandra/).
Our containers are based on Alpine Linux wich is a security-oriented, lightweight Linux distribution based on musl libc and busybox.
### Kubernetes
You can deploy it to Kubernetes using [example configs from Annon's Infra repo](https://github.com/Nebo15/annon.infra/blob/master/kubernetes).
### Docker Compose
For local environments we provide an [example Docker Compose configuration](https://github.com/Nebo15/annon.infra/tree/master/docker-compose). You can use this one-liner to deploy all Annon components on a local machine:
`curl -L http://bit.ly/annon_compose | bash`
## Source Code Documentation
Also there are auto-generated code documentation [available here](https://nebo15.github.io/annon.api/api-reference.html#content).
## License
See [LICENSE.md](https://github.com/Nebo15/annon.api/blob/master/LICENSE.md).
# Group APIs
API is a endpoint definition for any upstream back-end. They can be extended by Annons plugins.
#### Processing Order
Notice that even truough we trying to protect you from creating overllaping API configurations,
we can not guarantee that they always unique. API that was defined earlier will always have
higher priority, thus after creating overlapping API it won't work, but you won't break the one
that were working earlier.
### Pattern Matching
#### Wildcard Domains
In API request settings you can use `%` to match any substring in a request host. Eg: `%.example.com` will match `user1.example.com`.
#### API Path
In API request settings you can use `%` to match any substring in a request path. Eg: `/blog/%/comments` will match `/blog/my_post/comments` (and a `/blog/my_post/comments` since path is prefix for request).
## APIs [/apis]
### Get APIs [GET /apis{?name,limit,starting_after,ending_before}]
+ Parameters
+ name: `My API` (string, optional) - Filter APIs by their names.
+ limit: 20 (number, optional) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ starting_after: 56c31536a60ad644060041af (string, optional) - A cursor to fetch next page. Taken from collection response.
+ ending_before: 56c31536a60ad644060041aa (string, optional) - A cursor to fetch previous page. Taken from collection response.
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (array[`API__Response`])
### Create API [POST]
+ Request (application/json)
+ Attributes
+ api (`API__Request`, required)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`API__Response`)
+ Response 409 (application/json)
+ Attributes (Response_Error)
+ meta (Response__Meta)
+ code: 409 (number)
+ error (`Response__Error_DuplicateEntity`)
### Get API [GET /apis/{id}]
+ Parameters
+ id: 1 (string, required)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`API__Response`)
### Update or Create API [PUT /apis/{id}]
+ Parameters
+ id: 1 (string, required)
+ Request (application/json)
+ Attributes
+ api (`API__Request`, required)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`API__Response`)
+ Response 201 (application/json)
+ Headers
Location: /apis/1
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`API__Response`)
### Configure API [PATCH /apis/{id}]
+ Parameters
+ id: 1 (string, required)
+ Request (application/json)
+ Attributes (object)
+ api (object) - Any of API's fields.
+ name: my_api (string, optional) - Unique name for API.
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`API__Response`)
### Delete API [DELETE /apis/{id}]
+ Parameters
+ id: 1 (string, required)
+ Request (application/json)
+ Response 204 (application/json)
## Plugins [/apis/{api_id}/plugins]
This is a general section that describes methods for managing API Plugins. Each plugin has it's own settings structure, their description is provided in sections below.
### Get all Plugins binded to an API [GET]
+ Parameters
+ api_id: 1 (string, required)
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (array[Plugin])
### Update or Bind Plugin [PUT /apis/{api_id}/plugins/{plugin_name}]
+ Parameters
+ api_id: 1 (string)
+ plugin_name: proxy (string)
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Proxy__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Proxy__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Proxy__Response`)
### Unbind Plugin [DELETE /apis/{api_id}/plugins/{plugin_name}]
+ Parameters
+ api_id: 1 (string, required)
+ plugin_name: proxy (string, required)
+ Request (application/json)
+ Response 204 (application/json)
# Group Plugins
## Proxy [/apis/{api_id}/plugins/proxy]
Proxy allows:
- Send HTTP requests from API to a `upstream`.
- Modify path and trim API-related part from it.
- Add headers to upstream request (for example, to authentificate on back-end behind gateway).
- Proxy `X-Request-ID` header, so all upstream back-ends can log request state with same UUID.
### Strip Request Path
You can set `strip_api_path` setting if you want to exclude API-related prefix from upstream request.
Request Path | Proxy Path | API Path | `strip_api_path` | Upstream Request
------------ | ---------- | -------- | ------- | --------
`/api` | `/proxy` | `/api` | `false` | `/proxy/api`
`/api/foo` | `/proxy` | `/api` | `false` | `/proxy/api/foo`
`/api` | `/` | `/api` | `false` | `/api`
`/api/foo` | `/` | `/api` | `false` | `/api/foo`
`/api` | `/proxy` | `/api` | `true` | `/proxy`
`/api/foo` | `/proxy` | `/api` | `true` | `/proxy/foo`
`/api` | `/` | `/api` | `true` | `/`
`/api/foo` | `/` | `/api` | `true` | `/foo`
### Bind or Update Proxy Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Proxy__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Proxy__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Proxy__Response`)
## Authentication [/apis/{api_id}/plugins/auth]
This plugin authenticates API consumers by using a configured strategy.
Right now it supports two strategies:
- `jwt` - uses JSON Web Token to resolve consumer ID and scope.
- `oauth` - uses token from `Authorization: Bearer <token>` header and subsequent request to resolve consumer ID and scope via third-party provider.
### JWT Strategy
Decodes JWT tokens received from API Consumer and validates it signature by a configured secret key.
If token is invalid, appropriate error response will be send back to api consumer.
It requests `consumer_id` to be present in token itself, but Consumer `scope` can be resolved by:
1. Adding `scope` field in JWT token.
2. Subsequent request to a third-party provider.
**Warning!** JWT signature should be Base64 encoded. Some providers (for example, Auth0) already encode it for you.
#### Consumer Usage
Consumer should send `Authorization: Bearer <jwt_token>` header with his requests.
#### Subsequent requests
You can configure this strategy to resolve consumer scope by a subsequent request to a
third-party provider, in this case GET request will be send to `url_template`
with substituted `{consumer_id}`. Annon will expect `HTTP 200` response in following format:
```
{
"data": {
"user_id": "user-dsljsdflkdflj",
"details": {
"scope": "originator_loans:upload"
}
}
}
```
`$.data.user_id` will be mapped to Consumer ID.
`$.data.details.scope` will be mapped to Consumer Scope.
**OR**
```
{
"data": {
"consumer_id": "user-dsljsdflkdflj",
"consumer_scope": "originator_loans:upload"
}
}
```
If any other response is sent, Consumer will have no scopes but `X-Consumer-ID` header will be sent to upstream.
#### Auth0 Support
**Configuration**
To configure Annon copy-paste your `Client Secret` from `Clients` -> `Settings` to plugins `signature` configuration.
**Issuing a Token**
To receive an valid JWT with scopes token you must:
1. Set `app_metadata` for all your users, it should have AT LEAST one array with consumer ID:
```
{
"consumer_id": "my_consumer_id"
}
```
2. (Optional) If you prefer to receive scopes from Auth0 `app_metadata` should also have scopes array:
```
{
"consumer_id": "my_consumer_id",
"consumer_scope": "email:read email:send"
}
```
You can set default scopes in `Client` -> `Settings` -> `Advanced` -> `App Metadata`.
3. When authorizing consumers set correct scope to receive JWT token with `app_metadata`: `scope=openid app_metadata`.
4. Whenever you make requests to Annon, use `id_token` from Auth0 response (it's a JWT token that we need) in a `Authorization: Bearer <id_token>` header.
### oAuth Strategy
Recieves `access_token` from a `Authorization: Bearer <access_token>` header
and sends a subsequent request to resolve Consumer ID and scopes via third-party provider (eg. [Mithril](http://docs.mithril1.apiary.io/#)).
#### Consumer Usage
Consumer should send `Authorization: Bearer <access_token>` header with his requests.
#### Subsequent requests
GET request will be send to `url_template` with substituted `{access_token}`.
Annon will expect `HTTP 200` response in following formats:
```
{
"data": {
"user_id": "user-dsljsdflkdflj",
"details": {
"scope": "originator_loans:upload"
}
}
}
```
`$.data.user_id` will be mapped to Consumer ID.
`$.data.details.scope` will be mapped to Consumer Scope.
**OR**
```
{
"data": {
"consumer_id": "user-dsljsdflkdflj",
"consumer_scope": "originator_loans:upload"
}
}
```
If any other response is sent, Consumer will not be autheticated.
### Bind or Update Authentication Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Auth__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Auth__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Auth__Response`)
## ACL [/apis/{api_id}/plugins/acl]
ACL allows to set scope to access certain subpaths of your API.
Once enabled it will restrict access to all subpaths of API, and you
need to allow access to them by whitelisting paths or path patterns.
It expects scope to be set in Auth plugin, if scope is not set,
API consumers will receive responses `unathorized` error.
Proxy configuration consist of pattern matches on request method and path:
```
rules: [
{methods: ["GET", "POST", "PUT", "DELETE"], path: ".*", scopes: ["request_api"]},
{methods: ["GET"], path: "^/profiles/me", scopes: ["read_profile"]},
{methods: ["POST", "PUT"], path: "^/profiles/me", scopes: ["update_profile"]},
{methods: ["DELETE"], path: "^/profiles/me", scopes: ["delete_profile"]}
]
```
Path is relative to API path, so you **don't need to specify API path prefix**!
**All rules is applied in a order they were defined.**
### Bind or Update ACL Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_ACL__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_ACL__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_ACL__Response`)
## Validator [/apis/{api_id}/plugins/validator]
Validator plugin allows to set a [JSON Schema](http://json-schema.org/) to validate request to a API by pattern mathching request path:
```
rules: [
{methods: ["POST", "PUT"], path: ".*", schema: "{}"},
{methods: ["POST"], path: "^/profiles/me", schema: "{}"}
]
```
Path is relative to API path, so you **don't need to specify API path prefix**!
**All rules is applied in a order they were defined.**
### Bind or Update Validator Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Validator__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Validator__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Validator__Response`)
## Idempotency [/apis/{api_id}/plugins/idempotency]
Gateway supports idempotency for safely retrying POST requests without accidentally duplicating entity. Gateway always send back the same response for requests made with the same key.
However, you cannot use the same key with different request parameters.
To perform an idempotent request, send a POST requests with `X-Idempotency-Key: <idempotency_key>` header. `idempotency_key` can be any unique string up to 255 characters, we recommend to use UUIDs.
Enabling idempotency will increase response latency - Requests will be created synchronously to enshure read-after-write consistency.
### Bind or Update Idempotency Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Idempotency__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Idempotency__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Idempotency__Response`)
## IP Restriction [/apis/{api_id}/plugins/ip_restriction]
Whitelist or blacklist IP ranges from accessing an API.
You can specify matches by replacing ranges with `*`.
Rules applied in a predicted order:
* If there is an ip whitelist - block requests from IP's that not in this list.
* If IP is in blacklist and not in white list - block request.
* If IP is in blacklist and in whitelist - allow request.
### Bind or Update IP Restriction Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_IP_Restriction__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_IP_Restriction__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_IP_Restriction__Response`)
## User Agent Restriction [/apis/{api_id}/plugins/ua_restriction]
Whitelist or blacklist User Agents from accessing an API.
You can specify matches by replacing ranges with `*`.
Rules applied in a predicted order:
* If there is an User Agent whitelist - block requests from User Agents that not in this list.
* If User Agent is in blacklist and not in white list - block request.
* If User Agent is in blacklist and in whitelist - allow request.
### Bind or Update User Agent Restriction Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_UA_Restriction__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_UA_Restriction__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_UA_Restriction__Response`)
## CORS [/apis/{api_id}/plugins/cors]
Plugin allows to request your APIs with Cross-Origin Resource Sharing (CORS) mechanism.
When enabled requests to API will return the following headers:
On preflight (`OPTIONS`) requests:
- `Access-Control-Allow-Origin`
- `Access-Control-Allow-Credentials`
- `Access-Control-Max-Age`
- `Access-Control-Allow-Headers`
- `Access-Control-Allow-Methods`
On `GET`, `POST`, `PUT` and other requests:
- `Access-Control-Allow-Origin`
- `Access-Control-Expose-Headers`
- `Access-Control-Allow-Credentials`
### Bind or Update CORS Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_CORS__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_CORS__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_CORS__Response`)
## Rate Limit [/apis/{api_id}/plugins/rate_limit]
This plugin allows you to rate limit requests from API Consumers based on `X-Consumer-ID` header returned from authorization plugins.
If consumer is not identified, rate limit won't apply to it, since it's up to you how to configure API access policy.
**This plugin is in development.**
### Bind or Update Rate Limiter Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Rate_Limit__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Rate_Limit__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Rate_Limit__Response`)
## Load Shedding [/apis/{api_id}/plugins/load_shedding]
This plugin allows to set requests rate limits for an API and drops requests that go over the limit.
**This plugin is in development.**
### Bind or Update Load Shedding Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Load_Shedding__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Load_Shedding__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Load_Shedding__Response`)
## Static Responses [/apis/{api_id}/plugins/static_responses]
This plugin allows to serve static responses to API requests, wich allows you to build some responses directly at the edge instead of forwarding them to an internal cluster.
It can be used to mock service responses or to push common responses to the edge service.
**This plugin is in development.**
### Bind or Update Static Responses Plugin [PUT]
+ Parameters
+ api_id: 1 (string, required) - API ID.
+ Request (application/json)
+ Attributes
+ plugin (`Plugin_Static_Responses__Request`)
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Plugin_Static_Responses__Response`)
+ Response 201 (application/json)
+ Attributes (Response_OK)
+ meta (Response__Meta)
+ code: 201 (number)
+ data (`Plugin_Static_Responses__Response`)
# Group Requests
## Requests [/requests]
### Get all Requests [GET /requests{?idempotency_key,api_ids,status_codes,ip_addresses,limit,starting_after,ending_before}]
+ Parameters
+ `idempotency_key`: `my_idemp_key` (string, optional) - Filter Requests by idempotency key.
+ `api_ids`: `api_id1,api_id2` (string, optional) - List of API IDs to filter Requests, separated by comma.
+ `status_codes`: `200,201` (string, optional) - List of HTTP response status codes to filter Requests, separated by comma.
+ `ip_addresses`: `127.0.0.1,182.211.120.002` (string, optional) - List of IP Addresses to filter Requests, separated by comma.
+ limit: 20 (number, optional) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ starting_after: 56c31536a60ad644060041af (string, optional) - A cursor to fetch next page. Taken from collection response.
+ ending_before: 56c31536a60ad644060041aa (string, optional) - A cursor to fetch previous page. Taken from collection response.
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (array[Request])
### Get Request [GET /requests/{id}]
+ Parameters
+ id: `my_request-sfsdfjsdoqknjdnd` (string, required)
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (Request_Expanded)
### Delete Request [DELETE /requests/{id}]
+ Parameters
+ id: `my_request-sfsdfjsdoqknjdnd` (string, required)
+ Request (application/json)
+ Response 204 (application/json)
# Group Service Status
## Requests Metrics [/requests_metrics{?interval,api_ids}]
### Get Requests Metrics [GET]
+ Parameters
+ `interval`: `5 minute` (string, optional) - Interval for time-based aggregation of latencies data. Supports following formats: `5 minites`, `1 minute`, `1 hour, `5 hours`, `1 day`, `5 days`. Term count can be any number.
+ `api_ids`: `api_id1,api_id2` (string, optional) - List of API IDs to filter Requests, separated by comma.
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Metrics`)
## Cluster Status [/cluster_status]
### Get Cluster Status [GET]
+ Response 200 (application/json)
+ Attributes (Response_OK)
+ data (`Cluster_Status`)
## APIs Status [/apis_status{?interval}]
This endpoint can be publicly available (just configure API for it).
### Get APIs Status [GET]
This endpoint returns list of disclosed APIs statuses and can be used to render service status page.
+ Parameters
+ `interval`: `5 minute` (string, optional) - Interval for time-based aggregation of latencies data. Supports following formats: `5 minites`, `1 minute`, `1 hour, `5 hours`, `1 day`, `5 days`. Term count can be any number.
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (array[`API_Status`])
# Group Dictionaries
## Cluster Status [/dictionaries/plugins]
### Get all Plugins [GET]
+ Response 200 (application/json)
+ Attributes (Response_Collection)
+ data (`Plugin_Dictionary_Entry`)
# Data Structures
## Responses
### `Response_Collection`
+ meta (Response__Meta, fixed-type)
+ data (array[], fixed-type)
+ paging (Response__Pagination, fixed-type)
### `Response_OK`
+ meta (Response__Meta, fixed-type)
+ data (object, fixed-type)
### `Response_Error`
+ meta (Response__Meta, fixed-type)
+ code: 400 (number)
+ error (Response__Error, fixed-type)
### `Response__Meta`
+ code: 200 (number) - HTTP response code.
+ url: http://example.com/resource (string) - URL to requested resource.
+ type (enum) - Type of data that is located in `data` attribute.
- object (string) - `data` attribute is a JSON object.
- list (string) - `data` attribute is a list.
+ code: 200 (number) - HTTP response code.
+ `idempotency_key`: `idemp-ssjssdjoa8308u0us0` (string, optional) - [Idempotency key](http://docs.apimanifest.apiary.io/#introduction/optional-features/idempotent-requests). Send it trough `X-Idempotency-Key` header.
+ `request_id`: `req-adasdoijasdojsda` (string) - [Request ID](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/request-id). Send it with `X-Request-ID` header.
### `Response__Error`
+ type: type_atom (string) - Atom that represents error type.
+ message: Error description (string) - Human-readable error message. This is for developers, not end-users.
### `Response__Error_DuplicateEntity`
+ type: `object_already_exists` (string) - Atom that represents error type.
+ message: This API already exists (string) - Human-readable error message. This is for developers, not end-users.
### `Response__Error_ValidationFailed`
+ type: validation_failed (string) - type of an error.
+ message: Validation failed. You can find validators description at our API Manifest: http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors. (string)
+ invalid (array)
+ `entry_type`: `json_data_proprty` (string) - Type of error.
+ entry: $.cvv (string) - JSON Path to an invalid property.
+ rules (array)
+ rule: required (string) - String constant that represents validation rule type. List of all types can be found in [API Manifest](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors).
+ params (array) - Validation Parameters.
### `Response__Pagination`
+ limit: 20 (number) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ cursors (object)
+ `starting_after`: 56c31536a60ad644060041af (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
+ `ending_before`: 56c31536a60ad644060041aa (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
+ size: 1000 (number) - Total number of objects in collection.
+ has_more: false (boolean) - Is this collection have more data to load in the same style as last request loaded it.
## General
### `HTTP_Verb` (enum)
- POST (string)
- PUT (string)
- GET (string)
- DELETE (string)
### `Cluster_Status`
+ cluster_size: 3 (number) - Number of nodes joined to cluster.
+ cluster_strategy: `kubernetes` (enum) - Cluster formation strategy.
- `kubernetes` (string)
- `epmd` (string)
- `gossip` (string)
+ nodes (array[`Cluster_Node_Status`]) - List of nodes joined to a cluster and information about them.
+ open_ports (array[number]) - List of all opened ports.
- 80
- 8080
### `Cluster_Node_Status`
+ name: `nonode@nohost` (string)
+ otp_release: `19` (string)
+ process_count: 656 (number)
+ process_limit: 262144 (number)
+ run_queue: 0 (number)
+ uptime: 239.873 (number) - Seconds since node VM start.
### `Metrics`
+ latencies (array[API_Latencies])
+ `status_codes` (array[`Requests_Status_Codes`])
## APIs
### `API__Request`
+ name: my_api (string, required) - Unique name for API.
+ description: `My API example` (string, optional) - Description of an API.
+ docs_url: `http://docs.annon.apiary.io/` (string, optional) - Link to the API documentation page.
+ health (`API_Health`, optional)
+ request (`API_Request__Request`, fixed-type) - Request description.
+ disclose_status: false (boolean, optional) - If `true` API status will be publically available in API Status endpoint.
+ matching_priority: 1 (number, optional) - Priority in which APIs are matched agains consumer request path. Default value is 1.
### `API_Request__Request`
+ methods (array[`HTTP_Verb`], required) - HTTP request method.
+ scheme: http (string) - HTTP request scheme. May be: `http`, `https`.
+ host: `os-dev-gateway.nebo15.com` (string, required) - DNS address of your API or its IP.
+ port: 80 (number) - Port on which your API recieves requests.
+ path: /andrew/ (string, required) - Public path to your API. Must start with `/`. All requests that start with `path` will fall onto API rules.
### `API_Embed`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ name: my_api (string, required) - Unique name for API.
+ request (`API_Request__Request`, fixed-type) - Request description.
### `API__Response`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ Include API__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
### `API_Status`
+ id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ name: my_api (string, required) - Unique name for API.
+ description: `My API example` (string, optional) - Description of an API.
+ docs_url: `http://docs.annon.apiary.io/` (string, optional) - Link to the API documentation page.
+ health (`API_Health`)
+ metrics (object)
+ latencies (array[API_Latencies])
### `API_Health` (enum)
- `operational` (string)
- `degradated_perfomance` (string)
- `partial_outage` (string)
- `major_outage` (string)
### `API_Latencies`
+ api_id: 56c31536a60ad644060041af (string) - Unique ID for API.
+ `avg_client_request_latency`: 100 (number)
+ `avg_gateway_latency`: 2 (number)
+ `avg_upstream_latency`: 98 (number)
+ tick: `2017-04-20T19:15:00Z` (string, required) - ISO 8601 date and time in UTC timezone.
## Plugins
### Plugin
+ name: myplugin (string, required) - Plugin name
+ is_enabled: true (boolean, required) - Flag that shows that plagin is enabled or disabled.
+ settings (object, fixed-type) - Object that describes API plugin settings.
+ key: value - A key-value storage for your API plugins.
### `Plugin_Response`
+ Include Plugin
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
### `Plugin_Dictionary_Entry`
+ name: plugin_name (string) - Plugin name
+ validation_schema: `{}` (string) - JSON schema to validate plugin settings.
+ deps (array[]) - List of plugin names this plugin depends in runtime.
+ is_system: false (boolean) - System plugins can't be configured via ManagementAPI.
## Proxy Plugin
### `Plugin_Proxy__Request`
+ name: proxy (string, required)
+ is_enabled: true (boolean, required)
+ settings (Plugin_Proxy__Settings, fixed-type)
### `Plugin_Proxy__Response`
+ Include Plugin_Proxy__Request
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
### `Plugin_Proxy__Settings`
+ upstream (`Plugin_Proxy__Settings_Upstream`, required)
+ `preserve_host`: false (boolean, optional) - Keep HTTP HOST host header when proxying request to an upstream.
+ `strip_api_path`: false (boolean, optional) - Strip API part of path when sending request to upstream.
+ `additional_headers` (array[`Plugin_Proxy__Settings__Additional_Header`], optional) - Additional headers that should be sent to upstream.
+ `stripped_headers` (array[string], optional) - Headers that should NOT be sent to upstream.
+ `x-Unwanted-Header`
### `Plugin_Proxy__Settings__Additional_Header`
+ `X-Consumer-Header`: `header_value` (string)
### `Plugin_Proxy__Settings_Upstream`
+ scheme: https (string) - HTTP request scheme. May be: `http`, `https`, `amqp`, `ws`.
+ host: binlist.net (string) - DNS address of your upstream or its IP.
+ port: 443 (number) - Port on which your upstream recieves requests.
+ path: /json/545708 (string) - Path to your upstream API. You can omit this parameter to preserve path from original request.
## ACL Plugin
### `Plugin_ACL__Request`
+ name: acl (string, required)
+ is_enabled: true (boolean, required)