nexmo_api_specification 0.11.1 → 0.11.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a0384722a3859e07f8d1e928f128c9fc553dbfe
-  data.tar.gz: 5c57e55b250604aa1ac5acf6b2fa206b123821c7
+  metadata.gz: b5c8c40ce265d614d8a602e3cf2652dddb5c3fbb
+  data.tar.gz: e2545074caadbf429c03c1c319b656a7967c587a
 SHA512:
-  metadata.gz: 0d5c2a698f9cf9491677c12c0fb71f701a6f81f01a7622b763752be6a277889f61f959721f4e776e506a60c8efffef4905733cdb6c2c5cb3dde3eb223b115458
-  data.tar.gz: 9f04d65d503f4134093223b76bcc6918249d63dfe8b363e118b6435959a5f9988ccd36ae3e12d217320b6debb861251f85497597ad8461a8b36f45a211bfb1e5
+  metadata.gz: 01c84df8c3f285993f87ae39816bf4879c69f7506b686a7807beb39c6d0ff1b871264f5faac25b9d3d6f4660be46df0582065afbd824aa39853503aad6fde986
+  data.tar.gz: 55e0bab7af7b6136b79bae403c592c2e6356928f6b80c47e742eed1e1dae4650b8d18fc4f81f71d3aba08ecbf97b14802d9cec9f4f6fc470f3214c1afb33fe7f

data/definitions/number-insight.yml

@@ -331,7 +331,7 @@ components:
                     attribute: true
                 caller-name:
                   type: string
-                  description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+                  description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
                   example: 'John Smith'
                   xml:
                     attribute: true
@@ -353,7 +353,7 @@ components:
                     attribute: true
             caller_name:
               type: string
-              description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+              description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
               example: 'John Smith'
             last_name:
               type: string
@@ -422,7 +422,7 @@ components:
                     attribute: true
                 caller-name:
                   type: string
-                  description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+                  description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
                   example: 'John Smith'
                   xml:
                     attribute: true
@@ -444,7 +444,7 @@ components:
                     attribute: true
             caller_name:
               type: string
-              description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+              description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
               example: 'John Smith'
             last_name:
               type: string
@@ -646,7 +646,7 @@ components:
           $ref: '#/components/schemas/niCallerIdentity'
         caller_name:
           type: string
-          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
           example: 'John Smith'
         last_name:
           type: string
@@ -741,7 +741,7 @@ components:
           $ref: '#/components/schemas/niCallerIdentity'
         caller_name:
           type: string
-          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
           example: 'John Smith'
         last_name:
           type: string
@@ -926,7 +926,7 @@ components:
           example: 'consumer'
         caller_name:
           type: string
-          description: 'Full name of the person who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
+          description: 'Full name of the person or business who owns the phone number. `unknown` if this information is not available. This parameter is only present if `cnam` had a value of `true` within the request.'
           example: 'John Smith'
         first_name:
           type: string

data/definitions/sms.yml

@@ -119,9 +119,9 @@ components:
         to:
           description: The number that the message should be sent to
           type: string
-          minLength: 11
-          maxLength: 12
-          pattern: '\d{11,12}'
+          minLength: 7
+          maxLength: 15
+          pattern: '\d{7,15}'
           example: 447700900000
         text:
           description: The body of the message being sent
@@ -395,29 +395,7 @@ components:
           example: '2001011400'
         err-code:
           type: string
-          description: |
-            The status of the request. Will be a non `0` value if there has been an error.
-
-            Code | Description
-            -- | --
-            `0` | Delivered.
-            `1` | ^[Unknown](Either: An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.)
-            `2` | ^[Absent Subscriber Temporary](This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result.)
-            `3` | ^[Absent Subscriber Permanent](To is no longer active, you should remove this phone number from your database.)
-            `4` | ^[Call barred by user](You should remove this phone number from your database. If the user wants to receive messages from you, they need to contact their carrier directly.)
-            `5` | ^[Portability Error](There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.)
-            `6` | ^[Anti-Spam Rejection](Carriers often apply restrictions that block messages following different criteria. For example, on SenderID or message content.)
-            `7` | ^[Handset Busy](The handset associated with to was not available when this message was sent. If status is Failed, this is a temporary failure; retry later for a positive result. If status is Accepted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.)
-            `8` | ^[Network Error](A network failure while sending your message. This is a temporary failure, retry later for a positive result.)
-            `9` | ^[Illegal Number](You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.)
-            `10` | ^[Invalid Message](The message could not be sent because one of the parameters in the message was incorrect. For example, incorrect type or udh.)
-            `11` | ^[Unroutable](The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.)
-            `12` | ^[Destination unreachable](The message could not be delivered to the phone number.)
-            `13` | ^[Subscriber Age Restriction](The carrier blocked this message because the content is not suitable for to based on age restrictions.)
-            `14` | ^[Number Blocked by Carrier](The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.)
-            `15` | ^[Pre-Paid](Insufficent funds. To’s pre-paid account does not have enough credit to receive the message.)
-            `99` | ^[General Error](There is a problem with the chosen route to send your message. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.)
-
+          description: The status of the request. Will be a non `0` value if there has been an error. See the [SMS error reference](/api-errors/sms) for more details
           example: '0'
         message-timestamp:
           description: The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.
@@ -433,3 +411,71 @@ x-groups:
         $ref: '#/components/schemas/SMS'
       text/xml:
         $ref: '#/components/schemas/MessageXmlWrapper'
+
+x-errors:
+  1:
+    description: An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that `to` is unknown.
+    resolution: When you see this error, and status is rejected, always check if `to` in your request was valid.
+
+  2:
+    description: This message was not delivered because `to` was temporarily unavailable. For example, the handset used for to was out of coverage or switched off.
+    resolution: This is a temporary failure, retry later for a positive result.
+
+  3:
+    description: The `to` number is no longer active
+    resolution: Remove this phone number from your database.
+
+  4:
+    description: Call barred by user
+    resolution: You should remove this phone number from your database. If the user wants to receive messages from you, they need to contact their carrier directly.
+
+  5:
+    description: Portability error. There is an issue after the user has changed carrier for `to`
+    resolution: If the user wants to receive messages from you, they need to contact their carrier directly.
+
+  6:
+    description: Anti-Spam rejection. Carriers often apply restrictions that block messages following different criteria. For example, on SenderID or message content
+    resolution: If you believe that your message is being blocked incorrectly, either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com
+
+  7:
+    description: Handset busy. The handset associated with to was not available when this message was sent. 
+    resolution: If status is Failed, this is a temporary failure; retry later for a positive result. If status is Accepted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.
+
+  8:
+    description: Network error. A network failure occured while sending your message
+    resolution: This is a temporary failure, retry later for a positive result.
+
+  9:
+    description: Insufficent funds. `To`’s pre-paid account does not have enough credit to receive the message.
+    resolution: The `to` number must top up, then you can retry sending the message
+
+  10:
+    description: The message could not be sent because one of the parameters in the message was incorrect. For example, incorrect type or udh.
+    resolution: Check your outbound request and try again
+    link:
+      text: View API reference
+      url: /api/sms#send-an-sms
+
+  11:
+    description: The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by `from`.
+    resolution: Either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com
+
+  12:
+    description: Desintation unreachable. The message could not be delivered to the phone number.
+    resolution: Check that your `to` number is valid. Make sure to use the country prefix (e.g. `44` for the UK) and not a `0`
+
+  13:
+    description: The carrier blocked this message because the content is not suitable for `to` based on age restrictions.)
+    resolution: N/A
+
+  14:
+    description: The carrier blocked this message. This could be due to several reasons. For example, `to`'s plan does not include SMS or the account is suspended.
+    resolution: N/A
+
+  15:
+    description: You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.
+    resolution: N/A
+
+  99:
+    description: There is a problem with the chosen route to send your message
+    resolution: To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.

data/definitions/stitch.yml

@@ -12,6 +12,35 @@ info:
     email: ea-support@nexmo.com
   x-label: Developer Preview
 paths:
+  /legs:
+    get:
+      x-swagger-router-controller: listLegs
+      operationId: listLegs
+      x-group: leg
+      summary: List legs
+      responses:
+        '200':
+          $ref: '#/components/responses/LegsListed'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+  '/legs/{leg_id}':
+    parameters:
+      - name: leg_id
+        in: path
+        required: true
+        description: Leg ID
+        schema:
+          type: string
+    delete:
+      x-swagger-router-controller: deleteLeg
+      operationId: deleteLeg
+      x-group: leg
+      summary: Delete a leg
+      responses:
+        '200':
+          $ref: '#/components/responses/Success'
+        '400':
+          $ref: '#/components/responses/ClientError'
   /conversations:
     post:
       x-swagger-router-controller: createConversation
@@ -332,6 +361,12 @@ paths:
           $ref: '#/components/responses/FoundList'
 components:
   responses:
+    LegsListed:
+      description: List Legs Succesfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LegsListed'
     ConversationUpdated:
       description: Create / Update Conversation Successfully
       content:
@@ -519,6 +554,86 @@ components:
           schema:
             $ref: '#/components/schemas/UserDetails'
   schemas:
+    Leg:
+      discriminator:
+        propertyName: Leg
+      type: object
+      description: Leg
+      properties:
+        uuid:
+          type: string
+          description: Leg ID
+        type:
+          type: string
+        conversation_uuid:
+          type: string
+        status:
+          type: string
+        from:
+          type: string
+        to:
+          type: string
+        direction:
+          type: string
+        rate:
+          type: string
+        price:
+          type: string
+        duration:
+          type: string
+        network:
+          type: string
+        start_time:
+          type: string
+        end_time:
+          type: string
+      required:
+        - uuid
+        - type
+        - start_time
+        - end_time
+    Legs:
+      discriminator:
+        propertyName: Legs
+      type: object
+      description: Legs Object
+      properties:
+        count:
+          type: number
+          description: Count
+        page_size:
+          type: number
+        record_index:
+          type: number
+        _links:
+          type: object
+          properties:
+            self:
+              type: object
+              properties:
+                href:
+                  type: string
+        _embedded:
+          type: object
+          properties:
+            legs:
+              type: object
+              properties:
+                _links:
+                  type: array
+                  items:
+                    allOf:
+                      - $ref: '#/components/schemas/Leg'
+                      - type: object
+                        properties:
+                          _links:
+                            type: object
+                            properties:
+                              self:
+                                type: object
+                                properties:
+                                  href:
+                                    type: string
     CreateConversation:
       discriminator:
         propertyName: CreateConversation
@@ -532,22 +647,8 @@ components:
             not provided, one will be automatically generated.
         display_name:
           type: string
-        image_url:
-          type: string
-        numbers:
-          type: object
-          properties:
-            pstn:
-              type: string
-            sms:
-              type: string
-            sip:
-              type: string
-        properties:
-          type: object
-          properties:
-            ttl:
-              type: string
+          description: The display name of the conversation
+
       required:
         - display_name
         - image_url
@@ -579,22 +680,7 @@ components:
             not provided, one will be automatically generated.
         display_name:
           type: string
-        image_url:
-          type: string
-        numbers:
-          type: object
-          properties:
-            pstn:
-              type: string
-            sms:
-              type: string
-            sip:
-              type: string
-        properties:
-          type: object
-          properties:
-            ttl:
-              type: string
+
     Conversation:
       discriminator:
         propertyName: Conversation
@@ -609,30 +695,14 @@ components:
           description: Conversation Name
         display_name:
           type: string
-          description: Display Name
-        image_url:
-          type: string
-          description: Display Name
+          description: The display name of the conversation
         timestamp:
           type: string
-          description: Display Name
+          description: time when conversation was created
         sequence_number:
           type: string
-          description: Display Name
-        numbers:
-          type: object
-          properties:
-            pstn:
-              type: string
-            sms:
-              type: string
-            sip:
-              type: string
-        properties:
-          type: object
-          properties:
-            ttl:
-              type: string
+          description: the last event id
+
         members:
           type: array
           items:
@@ -667,12 +737,15 @@ components:
       properties:
         name:
           type: string
+          description: Unique name (within the same application) for the conversation.
         date_start:
           type: string
           format: dateTime
+          description: Return the records that occurred after this point in time.
         date_end:
           type: string
           format: dateTime
+          description: Return the records that occurred at this point in time.
         page_size:
           type: number
           minimum: 1
@@ -682,6 +755,7 @@ components:
           minimum: 0
         order:
           type: string
+          description: Return the records that in ascending or descending order. 
           enum:
             - asc
             - desc
@@ -691,16 +765,21 @@ components:
       discriminator:
         propertyName: ConversationsListed
       type: object
-      description: List Conversations Response Payload Object
+      description: List Conversations Response Payload Object.
       properties:
         count:
           type: number
+          description: The total number of records returned by your request.
         page_size:
           type: number
+          description: The amount of records returned in this response.
+
         record_index:
           type: number
+          description: Return page_size calls from this index in the response. That is, if your request returns 300 concersations, set record_index to 5 in order to return calls 50 to 59. The default value is 0. That is, the first page_size calls.
         _links:
           type: object
+          description: A series of links between resources in this API in the http://stateless.co/hal_specification.html.
           properties:
             self:
               type: object
@@ -737,6 +816,56 @@ components:
         - record_index
         - _links
         - _embedded
+    LegsListed:
+      discriminator:
+        propertyName: LegsListed
+      type: object
+      description: List Legs Response Payload Object
+      properties:
+        count:
+          type: number
+        page_size:
+          type: number
+        record_index:
+          type: number
+        _links:
+          type: object
+          properties:
+            self:
+              type: object
+              properties:
+                href:
+                  type: string
+              required:
+                - href
+          required:
+            - self
+        _embedded:
+          type: object
+          properties:
+            conversations:
+              type: array
+              items:
+                type: object
+                properties:
+                  uuid:
+                    type: string
+                  name:
+                    type: string
+                  href:
+                    type: string
+                required:
+                  - uuid
+                  - name
+                  - href
+          required:
+            - legs
+      required:
+        - count
+        - page_size
+        - record_index
+        - _links
+        - _embedded
     CreateDeviceObject:
       discriminator:
         propertyName: CreateDeviceObject
@@ -792,6 +921,7 @@ components:
           description: Event ID
         timestamp:
           type: string
+          description: time when event was created
         href:
           type: string
     EventRetrieved:
@@ -1309,3 +1439,11 @@ x-groups:
     schema:
       application/json:
         $ref: '#/components/schemas/EventCreated'
+  leg:
+    name: "Leg"
+    order: 4
+    description: >-
+      A leg can be a video call, IP call, or PSTN call that users participate in using multiple platforms. With this endpoint you can retrieve the details about all of the legs that took place in your application.
+    schema:
+      application/json:
+        $ref: '#/components/schemas/Leg'

data/guidelines/GUIDELINES.md

@@ -208,35 +208,53 @@ Generic, like a 200 used in most cases when no more specific code applies. More
 ### Error Messages
 Any non 200 response body should follow a standard format. This should be consistent for all products, as an error may be product specific (invalid parameters) or global in nature (invalid authorization). The [HTTP Problem draft][http_problem], specifically the [JSON Object][http-problem-object] provide a familiar format used by other APIs that provides a set of standard properties while allowing additional properties when needed for a particular error condition.
 
-Stealing the the examples from the draft:
+This is the minimum required in a response:
+
 ```
 HTTP/1.1 403 Forbidden
 Content-Type: application/problem+json
 Content-Language: en
 {
     "type": "https://example.com/Error#out-of-credit",
-    "detail": "Your current balance is 30, but that costs 50.",
-    "instance": "/account/12345/msgs/abc",
-    "balance": 30,
-    "accounts": ["/account/12345",
-                 "/account/67890"]
+    "title": "You do not have enough credit",
+    "instance": "<trace_id>"
+}
+```
+
+In some cases, you may wish to add additional detail to the error by adding a `detail` key
+
+```
+HTTP/1.1 403 Forbidden
+Content-Type: application/problem+json
+Content-Language: en
+{
+  "type": "https://example.com/Error#out-of-credit",
+  "title": "You do not have enough credit",
+  "detail": "Your current balance is 30, but that costs 50.",
+  "instance": "<trace_id>"
 }
 ```
+
+If there are lots of errors, you may choose to return them as structured data. In this case, you would not return `detail`, but instead add a new key at the top level and put the data inside that (see below for a list of additional keys). In this case, we're returning a set of validation errors:
+
 ``` 
 HTTP/1.1 400 Bad Request
 Content-Type: application/problem+json
 Content-Language: en
 {
-   "type": "https://example.net/validation-error",
-   "title": "Your request parameters didn't validate.",
-   "invalid_parameters": [ {
-                         "name": "age",
-                         "reason": "must be a positive integer"
-                       },
-                       {
-                         "name": "color",
-                         "reason": "must be 'green', 'red' or 'blue'"}
-                     ]
+  "type": "https://example.net/validation-error",
+  "title": "Your request parameters didn't validate.",
+  "instance": "<trace_id>",
+  "invalid_parameters": [
+    {
+      "name": "age",
+      "reason": "must be a positive integer"
+    },
+    {
+      "name": "color",
+      "reason": "must be 'green', 'red' or 'blue'"
+    }
+  ]
 }
 ```
 
@@ -244,6 +262,18 @@ Following REST patterns, `type` is both the identifier for the specific error (U
 `type`, `title`, `status`, `detail`, and `instance` [are the standard properties][http-problem-properties], as the example shows additional properties can be added if relevant to the error.
 Note that this means a single response can not contain both a success and a failure (or even two failures that are significant enough to require two different high level problems).
 
+To keep things consistent, only the following additional keys are available:
+
+| Key                | Example value                                            |
+|--------------------|----------------------------------------------------------|
+| invalid_parameters | [{"name": "age","reason": "must be a positive integer"}] |
+
+If you require an additional key, raise a pull request against this file with the new key and example value
+
+Error messages should be clear and instructive: as best as you can, tell the developer what they need to fix about their request to make it successful.
+
+Error messages MUST not reveal underlying implementation details (e.g. parser state, class/package names). This is both unhelpful (it tells the user what is wrong with the server's software rather than what is wrong with their request) and also potentially leaks valuable information that would enable a malicious actor to break the security of the system.
+
 ### Collection and Links
 - [HAL-JSON][hal] provides a consistent format supported by consumer and provider tooling. [Current Draft][hal-draft]
 - Allows resources to be embedded using an `_embedded` property (with a distinguishing key).
@@ -268,13 +298,19 @@ All new API's shall adhere to the principles of REST (http://www.ics.uci.edu/~fi
 - Collections are the collective term for Resources e.g. member
 - Resources are nouns not verbs
 - Collections are plurals
-- Use HTTP methods to map CRUD actions on Resources i.e. POST creates a new Resources in a Collection, DELETE removes a Resource, GET lists Resources and PUT changes a Resource
+- Use HTTP methods to map CRUD actions on Resources i.e. 
+  - POST creates a new Resources in a Collection
+  - DELETE removes a Resource
+  - GET lists Resources
+  - PUT replaces a complete Resource
+  - PATCH partially updates a Resource
 
 #### Examples
 - `GET members/` - lists all the resources of the collection members
 - `GET members/bob` - lists the details of bob who is a resources of the collection members
-- `POST members/harry` - create a new member called Harry
-- `PUT members/harry/phone` - update Harry's phone number
+- `POST members -d '{"name": "Harry", "age": 22, "phone_number": "14155550100"}'` - create a new member called Harry
+- `PUT members/harry -d '{"name": "Harry", "age": 23, "phone_number": "14155550100"}'` - replace all of Harry's details
+- `PATCH members/harry -d '{"age": 23}'` - update Harry's age only
 - `DELETE members/steve` - remove the member Steve from the collection
 
 ### Pagination

data/lib/nexmo_api_specification/version.rb

@@ -1,3 +1,3 @@
 module NexmoApiSpecification
-  VERSION = '0.11.1'.freeze
+  VERSION = '0.11.4'.freeze
 end

data/ncco-schema.json

@@ -300,6 +300,11 @@
                 "mp3",
                 "wav"
               ]
+            },
+             "split": {
+              "enum" : [
+                  "conversation"                
+              ]
             },
             "endOnSilence": {
               "type": "integer",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexmo_api_specification
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.11.4
 platform: ruby
 authors:
 - Adam Butler
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-05 00:00:00.000000000 Z
+date: 2018-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Provides Open API Spec 3 definitions for Nexmo APIs