nexmo_api_specification 0.6.1 → 0.7.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/definitions/conversation.yml +2 -1
- data/definitions/reporting.yml +400 -0
- data/definitions/sms.yml +2 -1
- data/guidelines/GUIDELINES.md +89 -1
- data/lib/nexmo_api_specification/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d8f9d62b6cc71ba0a14eba4ba83d6318da4a6b29
|
|
4
|
+
data.tar.gz: a5e22b5126eadd14a44eef0a0758030fcfbc1cb2
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 04af3bfe700d83719b6a08e507052e5422c9d2deb414ad4f192d97cfb000a6be444deef4907d5c0b2666e74d976124d5d03354f687d478bafd9e55115bc4f58d
|
|
7
|
+
data.tar.gz: 54daa61f9b58469c3fb59593eb187d4e27f39bfff707a9cdabff1394ecd3e4651d9a832509483873aaff3b349b6a54a7e053623435c73a83c6c18c427b536c7c
|
|
@@ -356,7 +356,8 @@ x-groups:
|
|
|
356
356
|
description: >-
|
|
357
357
|
A conversation is a shared core component that Nexmo APIs rely on. Conversations happen over multiple mediums and and can have associated Users through Memberships.
|
|
358
358
|
schema:
|
|
359
|
-
|
|
359
|
+
application/json:
|
|
360
|
+
$ref: '#/components/schemas/ConversationFull'
|
|
360
361
|
user:
|
|
361
362
|
name: "User"
|
|
362
363
|
order: 2
|
|
@@ -0,0 +1,400 @@
|
|
|
1
|
+
openapi: "3.0.0"
|
|
2
|
+
info:
|
|
3
|
+
version: 1.0.0
|
|
4
|
+
title: Nexmo Reporting API
|
|
5
|
+
description: >
|
|
6
|
+
Nexmo's Reporting API allows you to request a report of activity on your
|
|
7
|
+
Nexmo account.
|
|
8
|
+
contact:
|
|
9
|
+
name: Nexmo.com
|
|
10
|
+
email: devrel@nexmo.com
|
|
11
|
+
url: 'https://developer.nexmo.com/'
|
|
12
|
+
x-twitter: Nexmo
|
|
13
|
+
termsOfService: 'https://www.nexmo.com/terms-of-use'
|
|
14
|
+
license:
|
|
15
|
+
name: The MIT License (MIT)
|
|
16
|
+
url: 'https://opensource.org/licenses/MIT'
|
|
17
|
+
x-logo:
|
|
18
|
+
url: 'https://twitter.com/Nexmo/profile_image?size=original'
|
|
19
|
+
x-apiClientRegistration: 'https://dashboard.nexmo.com/sign-up'
|
|
20
|
+
servers:
|
|
21
|
+
- url: https://api.nexmo.com
|
|
22
|
+
paths:
|
|
23
|
+
"/v1/reports/":
|
|
24
|
+
post:
|
|
25
|
+
summary: Create a report
|
|
26
|
+
description: Request a report on your account activity
|
|
27
|
+
parameters:
|
|
28
|
+
- name: api_key
|
|
29
|
+
description: Your API key
|
|
30
|
+
required: true
|
|
31
|
+
in: query
|
|
32
|
+
example: abcd1234
|
|
33
|
+
schema:
|
|
34
|
+
type: string
|
|
35
|
+
minLength: 8
|
|
36
|
+
maxLength: 8
|
|
37
|
+
- name: api_secret
|
|
38
|
+
description: Your API secret. Required unless `sig` is provided
|
|
39
|
+
required: false
|
|
40
|
+
in: query
|
|
41
|
+
example: abcdef0123456789
|
|
42
|
+
schema:
|
|
43
|
+
type: string
|
|
44
|
+
minLength: 16
|
|
45
|
+
maxLength: 16
|
|
46
|
+
- name: sig
|
|
47
|
+
description: The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.nexmo.com/concepts/guides/signing-messages) for more details.
|
|
48
|
+
required: false
|
|
49
|
+
in: query
|
|
50
|
+
schema:
|
|
51
|
+
type: string
|
|
52
|
+
minLength: 16
|
|
53
|
+
maxLength: 16
|
|
54
|
+
requestBody:
|
|
55
|
+
required: true
|
|
56
|
+
content:
|
|
57
|
+
application/json:
|
|
58
|
+
schema:
|
|
59
|
+
$ref: '#/components/schemas/NewReportReq'
|
|
60
|
+
responses:
|
|
61
|
+
'200':
|
|
62
|
+
description: OK
|
|
63
|
+
content:
|
|
64
|
+
application/json:
|
|
65
|
+
schema:
|
|
66
|
+
$ref: '#/components/schemas/NewReportResp'
|
|
67
|
+
'400':
|
|
68
|
+
description: Bad Request
|
|
69
|
+
content:
|
|
70
|
+
application/json:
|
|
71
|
+
schema:
|
|
72
|
+
$ref: '#/components/schemas/NewReportErrorResp'
|
|
73
|
+
'401':
|
|
74
|
+
description: Unauthorized
|
|
75
|
+
content:
|
|
76
|
+
application/json:
|
|
77
|
+
schema:
|
|
78
|
+
$ref: '#/components/schemas/NewReportUnauthorizedResp'
|
|
79
|
+
'403':
|
|
80
|
+
description: Forbidden
|
|
81
|
+
content:
|
|
82
|
+
application/json:
|
|
83
|
+
schema:
|
|
84
|
+
$ref: '#/components/schemas/NewReportForbiddenResp'
|
|
85
|
+
"/v1/reports/{report_id}":
|
|
86
|
+
get:
|
|
87
|
+
summary: Get status of report
|
|
88
|
+
description: Retrieve status and metadata about a requested report.
|
|
89
|
+
parameters:
|
|
90
|
+
- name: api_key
|
|
91
|
+
description: Your API key
|
|
92
|
+
required: true
|
|
93
|
+
in: query
|
|
94
|
+
example: abcd1234
|
|
95
|
+
schema:
|
|
96
|
+
type: string
|
|
97
|
+
minLength: 8
|
|
98
|
+
maxLength: 8
|
|
99
|
+
- name: api_secret
|
|
100
|
+
description: Your API secret. Required unless `sig` is provided
|
|
101
|
+
required: false
|
|
102
|
+
in: query
|
|
103
|
+
example: abcdef0123456789
|
|
104
|
+
schema:
|
|
105
|
+
type: string
|
|
106
|
+
minLength: 16
|
|
107
|
+
maxLength: 16
|
|
108
|
+
- name: sig
|
|
109
|
+
description: The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.nexmo.com/concepts/guides/signing-messages) for more details.
|
|
110
|
+
required: false
|
|
111
|
+
in: query
|
|
112
|
+
schema:
|
|
113
|
+
type: string
|
|
114
|
+
minLength: 16
|
|
115
|
+
maxLength: 16
|
|
116
|
+
- name: report_id
|
|
117
|
+
in: path
|
|
118
|
+
schema:
|
|
119
|
+
type: string
|
|
120
|
+
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
|
|
121
|
+
description: UUID of the report
|
|
122
|
+
required: true
|
|
123
|
+
responses:
|
|
124
|
+
'200':
|
|
125
|
+
description: OK
|
|
126
|
+
content:
|
|
127
|
+
application/json:
|
|
128
|
+
schema:
|
|
129
|
+
$ref: '#/components/schemas/NewReportResp'
|
|
130
|
+
"/v3/media/{file_id}":
|
|
131
|
+
get:
|
|
132
|
+
summary: Get report data
|
|
133
|
+
description: Download a zipped archive of the rendered report. The file is available for download for 72 hours.
|
|
134
|
+
parameters:
|
|
135
|
+
- name: api_key
|
|
136
|
+
description: Your API key
|
|
137
|
+
required: true
|
|
138
|
+
in: query
|
|
139
|
+
example: abcd1234
|
|
140
|
+
schema:
|
|
141
|
+
type: string
|
|
142
|
+
minLength: 8
|
|
143
|
+
maxLength: 8
|
|
144
|
+
- name: api_secret
|
|
145
|
+
description: Your API secret. Required unless `sig` is provided.
|
|
146
|
+
required: false
|
|
147
|
+
in: query
|
|
148
|
+
example: abcdef0123456789
|
|
149
|
+
schema:
|
|
150
|
+
type: string
|
|
151
|
+
minLength: 16
|
|
152
|
+
maxLength: 16
|
|
153
|
+
- name: sig
|
|
154
|
+
description: The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](https://developer.nexmo.com/concepts/guides/signing-messages) for more details.
|
|
155
|
+
required: false
|
|
156
|
+
in: query
|
|
157
|
+
schema:
|
|
158
|
+
type: string
|
|
159
|
+
minLength: 16
|
|
160
|
+
maxLength: 16
|
|
161
|
+
- name: file_id
|
|
162
|
+
in: path
|
|
163
|
+
schema:
|
|
164
|
+
type: string
|
|
165
|
+
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
|
|
166
|
+
description: UUID of the file.
|
|
167
|
+
required: true
|
|
168
|
+
responses:
|
|
169
|
+
'200':
|
|
170
|
+
description: OK
|
|
171
|
+
content:
|
|
172
|
+
"application/octet-stream":
|
|
173
|
+
schema:
|
|
174
|
+
type: string
|
|
175
|
+
description: "ZIP file containing data of your report"
|
|
176
|
+
|
|
177
|
+
components:
|
|
178
|
+
schemas:
|
|
179
|
+
NewReportReq:
|
|
180
|
+
type: object
|
|
181
|
+
properties:
|
|
182
|
+
product:
|
|
183
|
+
type: string
|
|
184
|
+
description: Which product you wish to produce a report for.
|
|
185
|
+
example: SMS
|
|
186
|
+
enum:
|
|
187
|
+
- SMS # should become 'sms'
|
|
188
|
+
- VOICE-CALL # should become 'voice-call'
|
|
189
|
+
- NUMBER-VERIFY # should become 'verify-api'
|
|
190
|
+
- HLR-LOOKUP # should become 'number-insight'
|
|
191
|
+
- VERIFY-SDK # to be deprecated
|
|
192
|
+
sms_type:
|
|
193
|
+
type: string
|
|
194
|
+
description: "For SMS reports, this is required. MT returns 'Mobile Terminating' requests - outgoing messages. MO returns 'Mobile Originating' requests - incoming messages."
|
|
195
|
+
example: MT
|
|
196
|
+
enum:
|
|
197
|
+
- MT
|
|
198
|
+
- MO
|
|
199
|
+
direction:
|
|
200
|
+
type: string
|
|
201
|
+
description: "For voice call reports: direction of the request. If unspecified, both will be returned."
|
|
202
|
+
enum:
|
|
203
|
+
- inbound
|
|
204
|
+
- outbound
|
|
205
|
+
account_id:
|
|
206
|
+
type: string
|
|
207
|
+
description: The account ID or IDs (comma-separated) you wish to search for (especially useful for searching for subaccounts),
|
|
208
|
+
example: "abcdef01"
|
|
209
|
+
include_subaccounts:
|
|
210
|
+
type: boolean
|
|
211
|
+
description: Whether to include subaccounts. Defaults to false.
|
|
212
|
+
enum:
|
|
213
|
+
- true
|
|
214
|
+
- false
|
|
215
|
+
default: false
|
|
216
|
+
example: false
|
|
217
|
+
callback_url:
|
|
218
|
+
type: string
|
|
219
|
+
description: URL to send a callback to upon completion of the report creation.
|
|
220
|
+
format: uri
|
|
221
|
+
example: "https://requestb.in/12345"
|
|
222
|
+
start_date:
|
|
223
|
+
type: string
|
|
224
|
+
format: date
|
|
225
|
+
description: "ISO 8601 formatted date for when reports should begin. If unspecified, defaults to seven days ago."
|
|
226
|
+
example: "2017-12-24:00:00+0000"
|
|
227
|
+
end_date:
|
|
228
|
+
type: string
|
|
229
|
+
format: date
|
|
230
|
+
description: "ISO 8601 formatted date for when report should end. If unspecified, defaults to the current time."
|
|
231
|
+
example: "2017-12-31T23:59:59+0000"
|
|
232
|
+
client_ref:
|
|
233
|
+
type: string
|
|
234
|
+
description: For MT SMS reports - search only for messages with this `client_ref`.
|
|
235
|
+
maxLength: 40
|
|
236
|
+
minLength: 40
|
|
237
|
+
account_ref:
|
|
238
|
+
type: string
|
|
239
|
+
description: For MT SMS reports - search only for messages with this `account_ref`.
|
|
240
|
+
maxLength: 40
|
|
241
|
+
minLength: 40
|
|
242
|
+
to:
|
|
243
|
+
type: string
|
|
244
|
+
description: "For SMS, Voice and Verify reports - search only for interactions with this number."
|
|
245
|
+
from:
|
|
246
|
+
type: string
|
|
247
|
+
description: "For SMS reports - search only for messages from this alphanumeric sender ID."
|
|
248
|
+
status:
|
|
249
|
+
type: string
|
|
250
|
+
description: "Search by the response status of the product. See the relevant API documentation for the status codes for different Nexmo products."
|
|
251
|
+
application_id:
|
|
252
|
+
type: string
|
|
253
|
+
description: Search only for calls/conversations attached to a particular Application ID.
|
|
254
|
+
conversation_id:
|
|
255
|
+
type: string
|
|
256
|
+
description: Search only for Voice calls attached to this particular Conversation. This should omit the "CON-" prefix.
|
|
257
|
+
required:
|
|
258
|
+
- product
|
|
259
|
+
NewReportResp:
|
|
260
|
+
type: object
|
|
261
|
+
properties:
|
|
262
|
+
request_id:
|
|
263
|
+
type: string
|
|
264
|
+
description: UUID for the request.
|
|
265
|
+
example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
|
|
266
|
+
status:
|
|
267
|
+
type: string
|
|
268
|
+
description: The current status of the request.
|
|
269
|
+
example: PENDING
|
|
270
|
+
enum:
|
|
271
|
+
- PENDING
|
|
272
|
+
- PROCESSING
|
|
273
|
+
- SUCCESS
|
|
274
|
+
- FAILED
|
|
275
|
+
product:
|
|
276
|
+
type: string
|
|
277
|
+
description: Specifies which product you are producing a report for.
|
|
278
|
+
example: SMS
|
|
279
|
+
enum:
|
|
280
|
+
- SMS # should become 'sms'
|
|
281
|
+
- VOICE-CALL # should become 'voice-call'
|
|
282
|
+
- NUMBER-VERIFY # should become 'verify-api'
|
|
283
|
+
- HLR-LOOKUP # should become 'number-insight'
|
|
284
|
+
- VERIFY-SDK # to be deprecated
|
|
285
|
+
sms_type:
|
|
286
|
+
type: string
|
|
287
|
+
description: "For SMS reports, this is required. MT returns 'Mobile Terminating' requests - outgoing messages. MO returns 'Mobile Originating' requests - incoming messages."
|
|
288
|
+
example: MT
|
|
289
|
+
enum:
|
|
290
|
+
- MT
|
|
291
|
+
- MO
|
|
292
|
+
callback_url:
|
|
293
|
+
type: string
|
|
294
|
+
description: URL where a callback will be sent once the report has been completed.
|
|
295
|
+
format: uri
|
|
296
|
+
example: "https://requestb.in/12345"
|
|
297
|
+
start_date:
|
|
298
|
+
type: string
|
|
299
|
+
format: date
|
|
300
|
+
description: "ISO 8601 formatted date for when reports should begin."
|
|
301
|
+
example: "2017-12-24:00:00+0000"
|
|
302
|
+
end_date:
|
|
303
|
+
type: string
|
|
304
|
+
format: date
|
|
305
|
+
description: "ISO 8601 formatted date for when report should end."
|
|
306
|
+
example: "2017-12-31:00:00+0000"
|
|
307
|
+
client_ref:
|
|
308
|
+
type: string
|
|
309
|
+
description: For MT SMS reports - search only for messages with this `client_ref`.
|
|
310
|
+
maxLength: 40
|
|
311
|
+
example: myref
|
|
312
|
+
account_ref:
|
|
313
|
+
type: string
|
|
314
|
+
description: For MT SMS reports - search only for messages with this `account_ref`.
|
|
315
|
+
maxLength: 40
|
|
316
|
+
example: myaccountref
|
|
317
|
+
account_id:
|
|
318
|
+
type: string
|
|
319
|
+
description: Account ID for the report.
|
|
320
|
+
example: abcdef01
|
|
321
|
+
include_subaccounts:
|
|
322
|
+
type: boolean
|
|
323
|
+
description: Whether to include subaccounts. Defaults to false.
|
|
324
|
+
enum:
|
|
325
|
+
- true
|
|
326
|
+
- false
|
|
327
|
+
example: false
|
|
328
|
+
conversation_uuid:
|
|
329
|
+
type: string
|
|
330
|
+
description: For voice call data, this is used to filter the report to only contain calls belonging to a particular conversation.
|
|
331
|
+
url:
|
|
332
|
+
type: string
|
|
333
|
+
description: The URI from which the report can be downloaded. Only appears once report status has changed to SUCCESS.
|
|
334
|
+
format: "https://api.nexmo.com/v3/media/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
|
|
335
|
+
receive_time:
|
|
336
|
+
type: string
|
|
337
|
+
format: date
|
|
338
|
+
description: The date and time when the request for the report was receieved by Nexmo.
|
|
339
|
+
example: "2018-01-01T00:00:00Z"
|
|
340
|
+
_links:
|
|
341
|
+
$ref: '#/components/schemas/SelfOnlyLinkObject'
|
|
342
|
+
items_count:
|
|
343
|
+
type: integer
|
|
344
|
+
description: The number of rows in the resulting file (when report has been completed).
|
|
345
|
+
self_link:
|
|
346
|
+
type: string
|
|
347
|
+
format: uri
|
|
348
|
+
description: URI of this document.
|
|
349
|
+
example: "https://api.nexmo.com/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
|
|
350
|
+
required:
|
|
351
|
+
- request_id
|
|
352
|
+
- status
|
|
353
|
+
- product
|
|
354
|
+
- account_id
|
|
355
|
+
- start_date
|
|
356
|
+
- end_date
|
|
357
|
+
- url
|
|
358
|
+
- receive_time
|
|
359
|
+
- _links
|
|
360
|
+
NewReportErrorResp:
|
|
361
|
+
type: object
|
|
362
|
+
properties:
|
|
363
|
+
errors:
|
|
364
|
+
type: array
|
|
365
|
+
items:
|
|
366
|
+
type: string
|
|
367
|
+
example: "Unexpected token (END_OBJECT), expected FIELD_NAME: missing property 'product' that is to contain type id"
|
|
368
|
+
NewReportUnauthorizedResp:
|
|
369
|
+
type: object
|
|
370
|
+
properties:
|
|
371
|
+
type:
|
|
372
|
+
type: string
|
|
373
|
+
enum:
|
|
374
|
+
- "UNAUTHORIZED"
|
|
375
|
+
example: "UNAUTHORIZED"
|
|
376
|
+
error_title:
|
|
377
|
+
type: string
|
|
378
|
+
enum:
|
|
379
|
+
- "Unauthorized"
|
|
380
|
+
example: "Unauthorized"
|
|
381
|
+
NewReportForbiddenResp:
|
|
382
|
+
type: object
|
|
383
|
+
properties:
|
|
384
|
+
message:
|
|
385
|
+
type: string
|
|
386
|
+
enum:
|
|
387
|
+
- "User not authorized to query the requested data"
|
|
388
|
+
example: "User not authorized to query the requested data"
|
|
389
|
+
SelfOnlyLinkObject:
|
|
390
|
+
type: object
|
|
391
|
+
properties:
|
|
392
|
+
self:
|
|
393
|
+
type: object
|
|
394
|
+
properties:
|
|
395
|
+
href:
|
|
396
|
+
type: string
|
|
397
|
+
format: uri
|
|
398
|
+
description: URI of this document.
|
|
399
|
+
example: "https://api.nexmo.com/reports/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
|
|
400
|
+
|
data/definitions/sms.yml
CHANGED
data/guidelines/GUIDELINES.md
CHANGED
|
@@ -278,16 +278,104 @@ All new API's shall adhere to the principles of REST (http://www.ics.uci.edu/~fi
|
|
|
278
278
|
- `DELETE members/steve` - remove the member Steve from the collection
|
|
279
279
|
|
|
280
280
|
### Pagination
|
|
281
|
+
|
|
282
|
+
APIs at Nexmo shall use one of the following pagination schemes:
|
|
283
|
+
|
|
284
|
+
* Cursor based for ever-expanding data sets, or where it's infeasible to count
|
|
285
|
+
the total number of records e.g. Voice API call log. Cursor based
|
|
286
|
+
pagination is also used when data is programatically added to a data set e.g.
|
|
287
|
+
call recordings to the Media API
|
|
288
|
+
* Page based for small, managed APIs where the customer is in control of what
|
|
289
|
+
is in the data set e.g. Number pools
|
|
290
|
+
|
|
291
|
+
To the customer, having two different pagination methods is OK, as in practice
|
|
292
|
+
they should request the first page and then follow the `_links.next` URL to get
|
|
293
|
+
the next page.
|
|
294
|
+
|
|
295
|
+
Cursor implementation can be decided by the engineering team. Results returned
|
|
296
|
+
must be consistently ordered, and the customer can decide if the data set
|
|
297
|
+
is returned in ascending or descending order.
|
|
298
|
+
|
|
299
|
+
#### Cursor based
|
|
300
|
+
|
|
301
|
+
Nexmo APIs shall use a cursor as their pagination option unless otherwise
|
|
302
|
+
agreed with DevRel.
|
|
303
|
+
|
|
304
|
+
> Cursors, if you’re not familiar, are like pointers. Pointers point at things,
|
|
305
|
+
they reference a specific iota, a place in the list where your last request left
|
|
306
|
+
off. A bookmark with breadcrumbs built in. (via [Slack](https://api.slack.com/docs/pagination#cursors))
|
|
307
|
+
|
|
281
308
|
- There shall be a way to page through collections without additional filters.
|
|
282
309
|
- There shall be a way to page through collections with filters.
|
|
310
|
+
- Cursors shall not expire
|
|
283
311
|
- Paging shall use a standard set of hal+json `_links`
|
|
284
312
|
- `self` (current page, required)
|
|
285
313
|
- `next` (next page, optional)
|
|
286
314
|
- `prev` (previous page, optional)
|
|
287
315
|
- `first` (first page, required)
|
|
288
316
|
- `last` (last page, required)
|
|
289
|
-
- Paging `_links`
|
|
317
|
+
- Paging `_links` must include filters.
|
|
318
|
+
- The page size parameter must be called `page_size`
|
|
319
|
+
- The cursor parameter must be called `cursor`
|
|
320
|
+
|
|
321
|
+
```json
|
|
322
|
+
{
|
|
323
|
+
"page_size": 100,
|
|
324
|
+
"cursor": "19284743",
|
|
325
|
+
"_embedded": [
|
|
326
|
+
{"data": "here"}
|
|
327
|
+
],
|
|
328
|
+
"_links": {
|
|
329
|
+
"self": {
|
|
330
|
+
"href": "https://example.com/resource?page_size=100&order=asc&cursor=19284743"
|
|
331
|
+
},
|
|
332
|
+
"next": {
|
|
333
|
+
"href": "https://example.com/resource?page_size=100&order=asc&cursor=19291731"
|
|
334
|
+
},
|
|
335
|
+
"prev": {
|
|
336
|
+
"href": "https://example.com/resource?page_size=100&order=asc&cursor=19283018"
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
#### Page based
|
|
290
343
|
|
|
344
|
+
In certain situations (e.g. purchasing a number) it may be beneficial to skip
|
|
345
|
+
over pages if you're not interested in that data. In this situation, `page` and
|
|
346
|
+
`page_size` shall be used.
|
|
347
|
+
|
|
348
|
+
To add a new page-based public API, you must get agreement from DevRel.
|
|
349
|
+
|
|
350
|
+
- Paging shall use a standard set of hal+json `_links`
|
|
351
|
+
- `self` (current page, required)
|
|
352
|
+
- `next` (next page, optional)
|
|
353
|
+
- `prev` (previous page, optional)
|
|
354
|
+
- `first` (first page, required)
|
|
355
|
+
- `last` (last page, required)
|
|
356
|
+
- Paging `_links` must include filters.
|
|
357
|
+
- The page size parameter must be called `page_size`
|
|
358
|
+
- The page index parameter must be called `page`
|
|
359
|
+
|
|
360
|
+
```json
|
|
361
|
+
{
|
|
362
|
+
"page_size": 100,
|
|
363
|
+
"_embedded": [
|
|
364
|
+
{"data": "here"}
|
|
365
|
+
],
|
|
366
|
+
"_links": {
|
|
367
|
+
"self": {
|
|
368
|
+
"href": "https://example.com/resource?page_size=100&order=asc&page=3"
|
|
369
|
+
},
|
|
370
|
+
"next": {
|
|
371
|
+
"href": "https://example.com/resource?page_size=100&order=asc&page=4"
|
|
372
|
+
},
|
|
373
|
+
"prev": {
|
|
374
|
+
"href": "https://example.com/resource?page_size=100&order=asc&page=2"
|
|
375
|
+
}
|
|
376
|
+
}
|
|
377
|
+
}
|
|
378
|
+
```
|
|
291
379
|
|
|
292
380
|
API specs
|
|
293
381
|
---------
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: nexmo_api_specification
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.7.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Adam Butler
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2018-
|
|
11
|
+
date: 2018-02-06 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: bundler
|
|
@@ -67,6 +67,7 @@ files:
|
|
|
67
67
|
- Rakefile
|
|
68
68
|
- definitions/conversation.yml
|
|
69
69
|
- definitions/number-insight.yml
|
|
70
|
+
- definitions/reporting.yml
|
|
70
71
|
- definitions/sms.yml
|
|
71
72
|
- definitions/verify.yml
|
|
72
73
|
- guidelines/GUIDELINES.md
|