nexmo_api_specification 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d58ff0a85fd19af6b0a974e150263243b7a19a1
+  data.tar.gz: f2f92f490dc1910d2c08c01a46e8ba362ea3f7c1
+SHA512:
+  metadata.gz: 818c25089d9e658542d40190679b6b96f4ee1e3db2f2c2dd529bb2e23eeea9dc06e6eb5b072bbd5726141867e23545c01301b52625ed00fea682f91b9bf0a85d
+  data.tar.gz: 0325d43b77283bcd34d423f3d43b4608754408a5696a41963c3d2d1715fd93ecb75ed9730382e2bcf2dcfcc8d9f981fdaf35afca8d8cfc48b243e64aadaa39f4

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nexmo_api_specification.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Nexmo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+# API Specifications
+
+Provides Open API Specification 3 definitions for Nexmo APIs.
+
+These definitions provide a single point of truth that can be used end-to-end can we used to:
+
+- **Planning** Shared during product discussions for planning API functionality
+- **Implementation** Inform engineering during development
+- **Testing** As the basis for testing or mocking API endpoints
+- **Documentation** For producing thorough and interactive documentation
+- **Tooling** To generate server stubs and client SDKs.
+
+## Definitions
+
+| API | Definition owner | Contributors |
+| --- | ---------------- | ------------ |
+| SMS | - | Adam Butler |
+| Voice | - | - |
+| Verify | - | - |
+| Number Insight | - | - |
+| Conversation | Neil Stratford | Adam Butler |
+| Olympus | Hugh Hopkins |
+| Account | - | - |
+| Messages | - | - |
+| Messages | - | - |
+| Numbers | - | - |
+| Application | - | - |
+| Conversion | - | - |
+
+## Resources
+
+- [What is OpenAPI?](https://swagger.io/docs/specification/about/)
+- [A Visual Guide to What's New in Swagger 3.0](https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/)
+- [OAS3 Documentation](https://swagger.io/docs/specification/basic-structure/)
+- [OAS3 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
+- [OAS3 Examples](https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v3.0)
+
+## Tools
+
+- [Swagger Editor](http://editor.swagger.io/) - Can be used to edit OAS3 definitions, provides live reloading Swagger UI.
+- [Swagger 2.0 to OAS3 converter](https://openapi-converter.herokuapp.com/) - Unofficial converter that can be used to convert existing Swagger 2.0 definitions to OAS3 definitions.
+- [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) - A template-driven engine to generate documentation, API clients and server stubs in different languages by parsing OAS3 definitions.
+- [Swagger Parser](https://github.com/swagger-api/swagger-parser) - Standalone library for parsing OAS3 definitions from Java
+- [Nexmo Developer](https://github.com/Nexmo/nexmo-developer) - Nexmo Developer has it's own OAS3 definition parser and API reference UI.
+
+## Contributing
+
+Contributions are welcome, please follow [GitHub Flow](https://guides.github.com/introduction/flow/index.html)

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/conversation.yml

@@ -0,0 +1,369 @@
+openapi: 3.0.0
+servers:
+  - url: 'https://api.nexmo.com/beta'
+info:
+  version: 1.0.0
+  title: Conversation API
+  description: >-
+    The Nexmo Conversation API enables you to build conversation features where communication can take place across multiple mediums including IP Messaging, PSTN Voice, SMS and WebRTC Audio and Video. The context of the conversations is maintained though each communication event taking place within a conversation, no matter the medium.
+security:
+  - bearerAuth: []
+paths:
+  /conversations:
+    post:
+      security:
+        - bearerAuth: []
+      x-group: conversation
+      summary: Create a conversation
+      parameters:
+        - name: name
+          in: query
+          description: Conversation name, must be unique but will auto-generated if you do not provide it.
+          required: false
+          schema:
+            type: string
+        - name: display_name
+          in: query
+          description: A personal name of your choosing.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: conversations response
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: '#/components/schemas/Conversation'
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+  /conversations/{id}:
+    get:
+      x-group: conversation
+      summary: Retrieve a conversation
+      parameters:
+        - name: id
+          in: path
+          description: ID of the conversation
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: conversations response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ConversationFull'
+  /conversations/{id}/members:
+    get:
+      x-group: member
+      summary: Retrieve members of a conversation
+      parameters:
+        - name: id
+          in: path
+          description: ID of the conversation
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: members response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Member'
+    post:
+      x-group: member
+      summary: Add a user to a conversation
+      parameters:
+        - name: id
+          in: path
+          description: tags to filter by
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: members response
+          content:
+            application/json:
+              schema:
+                type: object
+                $ref: '#/components/schemas/MemberFull'
+  /users:
+    get:
+      x-group: user
+      summary: Retrieve all users
+      responses:
+        '200':
+          description: users response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/UserFull'
+    post:
+      x-group: user
+      summary: Create a user
+      parameters:
+        - name: name
+          in: query
+          description: The users name
+          example: Dillon
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: users response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+  /users/{id}:
+    get:
+      x-group: user
+      summary: Retrive a user
+      parameters:
+        - name: id
+          in: path
+          description: The users ID
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: user response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserShow'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+  responses:
+    UnauthorizedError:
+      description: Access token is missing or invalid
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - code
+              - description
+            properties:
+              code:
+                type: 'string'
+                example: 'system:error:invalid-token'
+              description:
+                type: string
+                example: 'the token was rejected'
+  schemas:
+    CreatedTimestamp:
+      properties:
+        created:
+          example: "2020-01-01T12:00:00.000Z"
+          type: string
+          description: The time the conversation was created
+    JoinedTimestamp:
+      properties:
+        joined:
+          example: "2020-01-01T12:00:00.000Z"
+          type: string
+    Link:
+      properties:
+        self:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/Self'
+    Self:
+      properties:
+        href:
+          example: "http://conversation.local/v1/conversations/CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+    Embedded:
+      properties:
+        legs:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/Leg'
+    Leg:
+      properties:
+        _links:
+          type: array
+          example: []
+    Channel:
+      properties:
+        type:
+          type: string
+          example: app
+    MemberFull:
+      properties:
+        id:
+          example: "MEM-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+        user_id:
+          example: "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+        state:
+          example: "JOINED"
+          type: string
+        timestamp:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/JoinedTimestamp'
+        channel:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/Channel'
+        href:
+          example: 'http://conversation.local/v1/conversations/CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab/MEM-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+          type: string
+    Member:
+      properties:
+        user_id:
+          example: "USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+        name:
+          example: "MEM-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+        user_name:
+          example: "Dillon"
+          type: string
+        state:
+          example: "JOINED"
+          type: string
+    ConversationFull:
+      properties:
+        uuid:
+          example: "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
+          type: string
+          description: >-
+            Unique identifier for the conversation
+        name:
+          example: "nexmo-chat"
+          type: string
+          description: >-
+            The name of the conversation
+        display_name:
+          example: "Nexmo Chat"
+          type: string
+          description: >-
+            The display name of the conversation
+        timestamp:
+          type: object
+          items:
+            $ref: '#/components/schemas/CreatedTimestamp'
+        sequence_number:
+          example: 0
+          type: integer
+        numbers:
+          example: {}
+          type: string
+        properties:
+          example: {}
+          type: string
+        members:
+          example: []
+          type: array
+        api_key:
+          example: "abcd1234"
+          type: string
+          description: The API Key of the owner of the conversation
+        _links:
+          example:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/Link'
+        _embedded:
+          type: object
+          allOf:
+            - $ref: '#/components/schemas/Embedded'
+    Conversation:
+      type: object
+      required:
+        - id
+        - href
+      properties:
+        id:
+          type: string
+          example: 'CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+        href:
+          type: string
+          example: 'http://conversation.local/v1/conversations/CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+    UserShow:
+      type: object
+      required:
+        - name
+        - id
+        - href
+      properties:
+        id:
+          type: string
+          example: 'USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+        href:
+          type: string
+          example: 'http://conversation.local/v1/users/USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+        name:
+          type: string
+          example: 'Dillon'
+        channels:
+          type: object
+          example: {}
+    User:
+      type: object
+      required:
+        - name
+        - id
+        - href
+      properties:
+        id:
+          type: string
+          example: 'USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+        href:
+          type: string
+          example: 'http://conversation.local/v1/users/USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+    UserFull:
+      type: object
+      required:
+        - name
+        - id
+        - href
+      properties:
+        name:
+          type: string
+          example: 'Dillon'
+        id:
+          type: string
+          example: 'USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+        href:
+          type: string
+          example: 'http://conversation.local/v1/users/USR-aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
+x-groups:
+  conversation:
+    name: "Conversation"
+    order: 1
+    description: >-
+      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.
+    schema:
+      $ref: '#/components/schemas/ConversationFull'
+  user:
+    name: "User"
+    order: 2
+    description: >-
+      The concept of a user exists in Nexmo APIs, you can associate one with a user in your own application if you choose. A user can have multiple memberships to conversations and can communicate with other users through various different mediums.
+  member:
+    name: "Member"
+    order: 3
+    description: >-
+      Memberships connect users with conversations. Each membership has one conversation and one user however a user can have many memberships to conversations just as conversations can have many members.

data/guidelines/GUIDELINES.md

@@ -0,0 +1,313 @@
+# API Design Guidelines
+
+- [Names and Formats](#names-and-formats)
+- [Response Structure](#response-structure)
+- [Behaviour](#behaviour)
+- [API Spec](#api-spec)
+- [Versioning](#versioning)
+
+Names and Formats
+-----------------
+
+### Convention
+- Have parameters / properties in lower case with underscores. 
+- Have identifiers following the format: type_id. (message_id, recording_id, etc)
+- Use distinguishers only when the name is non-intuitive or conflicts with another name. (`count` instead of `message_count` because message should be intuitive, but `carrier_network` if there's also a roaming network)
+- Limit parameter / property names to a single underscore.
+- Reuse parameter / property names. (`from` instead of `msisdn`)
+
+#### Examples
+- `machine_detection`
+- `call_id`
+- `conference_id`
+
+### Objects retrieved via webhooks by the API (*Discussion Required*)
+Objects retrieved via webhooks by the API are in camelCase. 
+
+#### For example:
+Nexmo Call Control Objects (NCCO) examples:
+- `eventUrl`
+- `musicOnHold`
+- `beepOnStart`
+
+### Decimal precision
+All values returned by Nexmo shall have the same decimal precision. Suggested is 4 decimal point to match pricing. For example: `credit-limit: "0.0000"`.
+
+### Generic Naming
+The following parameters are included for all APIs:
+
+#### `identifier`
+	
+A string that identifies a specific communication device or endpoint. Can be an:
+- E.164 number
+- sip address 
+- The UUID of a web rtc client
+- ...
+
+An API may restrict which types of identifiers are accepted. For example, Number Insight will only accept an E.164 number for the 'identifier' parameter.
+
+#### `to`
+
+The identifier of a message or conversation recipient. This represents either:
+  - The app sending an outbound message 
+  - The user contacting the app with an inbound messages
+
+#### `from`	
+
+The identifier of a message sender or the initiator of a conversation. This represents either:
+- The app sending an outbound message 
+- The user contacting the app with an inbound messages
+
+#### `reference`
+
+The reference associating this request with the customer's internal data systems.
+
+#### `<description>_url`
+
+A url that is necessary for communication. For example, `callback_url`.
+
+#### `<description>_method`
+
+send the callback using either GET or POST.
+
+#### `ttl`
+
+Total time to live is the time during which this request is valid.
+
+#### `<description>_id`
+
+The unique identifier assigned by Nexmo for your request.
+
+#### `mccmnc`
+
+the country and carrier code for the carrier who handled your request.
+
+#### `language`
+
+The language used for the communication in https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. For example, en-US.
+
+#### `count`
+
+The number of parts your message was divided into in order to be sent correctly.
+
+#### `total` 
+
+The amount of objects found as a result of a search request.
+
+#### `direction`
+
+Set to true if the communication is inbound.
+
+#### `start`
+
+The time the communication started in https://en.wikipedia.org/wiki/ISO_8601 format.
+
+#### `end`
+
+The time the communication ended in https://en.wikipedia.org/wiki/ISO_8601 format.
+
+#### `duration`
+
+The duration of the call in seconds.
+
+#### `index`
+
+The index of this message in relation to count.
+
+#### `balance`
+
+The amount of money left in your Nexmo account.
+ 
+#### `rate`
+
+The price for each request. This is per request for text based messages, or per second for voice.
+
+#### `cost`
+
+The total cost that is the result of the request. 
+
+
+Response Structure
+---------------
+### Data Structure
+- Each API defines a single data structure and set of properties (resource). This must be coherent with the other APIs.
+- The data structure must be uniform regardless of the context. An SMS record is always the same, a number is always the same.
+- Data structures can be used as properties of other responses.
+- In each context properties that are always unknown may be omitted. For example: a request to sending an SMS never contains DLR data.
+- Properties that are potentially unknown should be included, but without a value. For example, if the Cloud Communications Platform cannot call the phone number defined in a request from Call API, the return properties will not have a valid `call_start` and `call_end`.
+
+#### Example Response 
+(common data structure for 'number')
+
+```json
+{
+    "call_id": "abcd1234",
+    "start_time": "123456789",
+    "end_time": "123456799",
+    "to": {
+        "type": "e.164",
+        "address": "+14445556767"
+    },
+    "from": {
+        "type": "sip",
+        "address": "user@example.com"
+    }
+}
+```
+
+### HTTP Status Codes
+API must express the general status of the request using HTTP status codes. Specific errors can be expressed in the response body.
+
+#### Success: 2XX
+
+##### 200: OK
+Generic, and used when no more specific code is relevant. For example: `GET /plots/p123`, or `PUT /plots/p123?overthrow=true`
+
+##### 201: Created	
+Used when a new resource has been created. Should (per HTTP spec) contain a `Location` header with the URI for the created resource. Avoiding any body here forces the client to only ever get the resource data from the URI.
+For example: `POST /plots?overthrow=true&date=tomorrow` => `Location: /plots/p124`
+
+##### 202: Accepted	
+Acknowledges the request has been received, but not that the process has been completed. Used for asynchronous tasks. Response body should include some kind of status, and a way to poll for status.
+Should avoid this in favor of creating a 'workflow' resource for anything complex.
+
+#### 204: No Content
+Generally used on a successful DELETE. As the resource has been deleted there is no body.
+
+#### Client errors: 4XX
+
+##### 400: Bad Request	
+Generic, like a 200 used in most cases when the request is incorrect and no more specific code applies. More details should be available (specific error, and human description) in the response body.
+
+##### 401: Unauthorized	
+Request is missing API authorization credentials, or those credentials are invalid.
+
+##### 403: Forbidden
+The authenticated user can not make this request. This is not an authentication issue, this is an authorization issue (could be due to low balance, scope of the auth token used, etc).
+
+##### 404: Not Found	
+The resource could not be found. If the URI format is correct with the exception of the resource ID, the body should include the same structured error response as any other API error.
+For example: `GET /plans/p125`
+
+##### 409: Conflict
+The request could not be completed due to a conflict with the current state of the resource. The resource exists; however, the action could not be taken. The response MUST contain contain a description of the conflict.
+For example: `PUT /calls/123/talk`
+
+##### 410: Gone
+The requested resource is no longer available at the server. This condition is expected to be considered permanent. Used when the URI is formatted correctly, but the subresource is no long available.
+For example: `PUT /calls/123/talk`
+
+##### 429: Too Many Requests
+Not in the official spec (rather a part of RFC 6585), response used when request is rate-limited. Used enough to be well understood.
+
+#### Server Errors(5XX)	
+
+##### 500: Internal Server Error
+Generic, like a 200 used in most cases when no more specific code applies. More details should be available (specific error, and human description) in the response body.
+
+### 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:
+```
+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"]
+}
+```
+``` 
+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'"}
+                     ]
+}
+```
+
+Following REST patterns, `type` is both the identifier for the specific error (URI) and a link to human readable documentation about the problem.
+`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).
+
+### 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).
+- Collections are simply resources that embed a set of resources of the same type.
+- Collections are not limited to a fixed set of properties (can create collection specific properties like 'queuedCalls' to provide a count of a subset).
+- Related resources will be referenced under a `_links` property.
+- There will always be a `_links.self` to the current resource.
+- Paging will use `_links`.
+
+
+Behavior
+--------
+- Updating resources will fail if required parameters are not set.
+- Unsent optional parameters will not be overwritten with default values.
+- Response for a POST or GET will be the same resource.
+- All APIs that allow updating a resource will also allow fetching a resource.
+
+### REST
+All new API's shall adhere to the principles of REST (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm). In doing so the following shall apply:
+
+- Separate things into logical Collections e.g. members
+- 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
+
+#### 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
+- `DELETE members/steve` - remove the member Steve from the collection
+
+### Pagination
+- There shall be a way to page through collections without additional filters.
+- There shall be a way to page through collections with filters.
+- Paging shall use a standard set of hal+json `_links`
+  - `self` (current page, required)
+  - `next` (next page, optional)
+  - `prev` (previous page, optional)
+  - `first` (first page, required)
+  - `last` (last page, required)
+- Paging `_links` will include filters.
+
+
+API specs
+---------
+Every API shall be described using the [OpenAPI Specification][oai].
+
+
+Versioning
+----------
+Nexmo APIs will support versioning. The version is given in the URI.
+
+### Deprecation
+When the decision has been taken to deprecate an API:
+- There will be a 1 year grace period between the announcement and the moment when API is deactivated. 
+- Warning emails will be sent to the API at regular intervals before the deprecation time
+- A guide will be supplied to customers explaining how to migrate to the replacement API with the initial deprecation notice. 
+
+
+[hal]: http://stateless.co/hal_specification.html
+[hal-draft]: https://tools.ietf.org/html/draft-kelly-json-hal-07
+[oai]: https://github.com/OAI/OpenAPI-Specification
+[http-problem-properties]: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-02#section-3.1
+[http-problem]: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-02
+[http-problem-object]: https://tools.ietf.org/html/draft-ietf-appsawg-http-problem-02#section-3

data/guidelines/README.md

@@ -0,0 +1,7 @@
+# Nexmo API Design Guidelines
+
+- Define common aspects of API design to output a consistent interface.
+- Expose those guidelines to provide:
+  - a process of adopting new guidelines.
+  - open communication around defining guidelines.
+  - an easily accessed history of changes.

data/lib/nexmo_api_specification/definition.rb

@@ -0,0 +1,8 @@
+module NexmoApiSpecification
+  module Definition
+    def self.load(definition)
+      raise 'Definition does not exist' unless File.exist? "#{definition}.yml"
+      File.read "#{definition}.yml"
+    end
+  end
+end

data/lib/nexmo_api_specification/version.rb

@@ -0,0 +1,3 @@
+module NexmoApiSpecification
+  VERSION = "0.1.0"
+end

data/lib/nexmo_api_specification.rb

@@ -0,0 +1,5 @@
+require 'nexmo_api_specification/version'
+
+module NexmoApiSpecification
+  require 'nexmo_api_specification/definition'
+end

data/nexmo_api_specification.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'nexmo_api_specification/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'nexmo_api_specification'
+  spec.version       = NexmoApiSpecification::VERSION
+  spec.authors       = ['Adam Butler']
+  spec.email         = ['adam.butler@nexmo.com']
+
+  spec.summary       = 'Provides Open API Spec 3 definitions for Nexmo APIs'
+  spec.homepage      = 'https://github.com/nexmo/api-specification'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+end

data/sms.yml

@@ -0,0 +1,213 @@
+openapi: 3.0.0
+servers:
+  - url: 'https://rest.nexmo.com'
+info:
+  title: SMS API
+  version: v1.0.0
+  description:
+    With the Nexmo SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers.
+paths:
+  '/sms/{format}':
+    post:
+      x-group: sms
+      summary: Send an SMS
+      description: Send an outbound SMS from your Nexmo account
+      parameters:
+        - name: format
+          description: The format of the response
+          required: true
+          in: path
+          example: json
+          type: string
+          enum:
+            - json
+            - xml
+          default: json
+        - name: api_key
+          description: Your API key
+          required: true
+          in: query
+          example: abcd1234
+          schema:
+            type: string
+            minLength: 8
+            maxLength: 8
+        - name: api_secret
+          description: Your API secret. Required unless `sig` is provided
+          required: false
+          in: query
+          example: abcdef0123456789
+          schema:
+            type: string
+            minLength: 16
+            maxLength: 16
+        - name: sig
+          description: The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See [Signing Requests](/concepts/guides/signing-messages) for more details.
+          required: false
+          in: query
+          schema:
+            type: string
+            minLength: 16
+            maxLength: 16
+      responses:
+        '200':
+          description: Success
+          content:
+            '*/*':
+              schema:
+                $ref: '#/components/schemas/SMS'
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                from:
+                  description: The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see [Global Messaging](/messaging/sms/guides/global-messaging#country-specific-features) for more details.
+                  type: string
+                  example: 'Acme Inc'
+                  required: true
+                to:
+                  description: The number that the message should be sent to
+                  type: string
+                  minLength: 11
+                  maxLength: 12
+                  pattern: '\d{11,12}'
+                  example: 447700900000
+                  required: true
+                text:
+                  description: The body of the message being sent
+                  type: string
+                  example: Hello World!
+                ttl:
+                  description: '**Advanced**: The duration in milliseconds the delivery of an SMS will be attempted.§§ By default Nexmo attempt delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.'
+                  type: integer
+                  example: 900000
+                  default: 259200000
+                  minimum: 20000
+                  maximum: 604800000
+                status-report-req:
+                  description: '**Advanced**: Boolean indicating if you like to receive a [Delivery Receipt](/messaging/sms/building-blocks/receive-a-delivery-receipt).'
+                  type: boolean
+                  example: 'false'
+                  default: 'true'
+                callback:
+                  description: '**Advanced**: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard.'
+                  type: string
+                  example: 'https://example.com/sms-dlr'
+                message-class:
+                  description: '**Advanced**: The Data Coding Scheme value of the message'
+                  type: integer
+                  enum:
+                    - 0
+                    - 1
+                    - 2
+                    - 3
+                type:
+                  description: '**Advanced**: The format of the message body'
+                  type: string
+                  enum:
+                    - text
+                    - binary
+                    - wappush
+                    - unicode
+                    - vcal
+                    - vard
+                  example: text
+                  default: text
+                vcard:
+                  description: '**Advanced**: A business card in [vCard format](https://en.wikipedia.org/wiki/VCard). Depends on `type` parameter having the value `vcard`.'
+                  type: vcard
+                vcal:
+                  description: '**Advanced**: A calendar event in [vCal format](https://en.wikipedia.org/wiki/VCal). Depends on `type` parameter having the value `vcal`.'
+                  type: vcal
+                body:
+                  description: '**Advanced**: Hex encoded binary data. Depends on `type` parameter having the value `binary`.'
+                  type: string
+                  example: 0011223344556677
+                udh:
+                  description: '**Advanced**: Your custom Hex encoded [User Data Header](https://en.wikipedia.org/wiki/User_Data_Header). Depends on `type` parameter having the value `binary`.'
+                  type: string
+                  example: 06050415811581
+                protocol-id:
+                  description: '**Advanced**: The value of the [protocol identifier](https://en.wikipedia.org/wiki/GSM_03.40#Protocol_Identifier) to use. Ensure that the value is aligned with `udh`.'
+                  type: integer
+                  example: 127
+                title:
+                  description: '**Advanced**: The title for a wappush SMS. Depends on `type` parameter having the value `wappush`.'
+                  type: string
+                  example: Welcome
+                url:
+                  description: '**Advanced**: The URL of your website. Depends on `type` parameter having the value `wappush`.'
+                  type: string
+                  example: https://example.com
+                validity:
+                  description: '**Advanced**: The availability for an SMS in milliseconds. Depends on `type` parameter having the value `wappush`.'
+                  type: string
+                  example: https://example.com
+
+components:
+  schemas:
+    Error:
+      type: object
+      properties:
+        message-count:
+          type: integer
+          description: The amount of messages in the request
+          example: 1
+        messages:
+          $ref: '#/components/schemas/ErrorMessage'
+    ErrorMessage:
+      type: object
+      properties:
+        status:
+          type: string
+          description: The error status of the message
+          example: '2'
+        error-text:
+          type: string
+          description: The description of the error
+          example: 'Missing to param'
+    SMS:
+      type: object
+      properties:
+        message-count:
+          type: integer
+          description: The amount of messages in the request
+          example: 1
+        messages:
+          $ref: '#/components/schemas/Message'
+    Message:
+      type: object
+      properties:
+        to:
+          type: string
+          description: The number the message was sent to
+          example: '447700900000'
+        message-id:
+          type: string
+          description: The ID of the message
+          example: 0A0000000123ABCD1
+        status:
+          type: string
+          description: The status of the message
+          example: '0'
+        remaining-balance:
+          type: string
+          description: Your remaining balance
+          example: '3.14159265'
+        message-price:
+          type: string
+          description: The cost of the message
+          example: '0.03330000'
+        network:
+          type: string
+          description: The ID of the network of the recipient
+          example: '12345'
+x-groups:
+  sms:
+    name: "SMS"
+    order: 1
+    description: The SMS object contains information about the request and details of the message information.
+    schema:
+      $ref: '#/components/schemas/SMS'

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: nexmo_api_specification
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Adam Butler
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-10-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- adam.butler@nexmo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- conversation.yml
+- guidelines/GUIDELINES.md
+- guidelines/README.md
+- lib/nexmo_api_specification.rb
+- lib/nexmo_api_specification/definition.rb
+- lib/nexmo_api_specification/version.rb
+- nexmo_api_specification.gemspec
+- sms.yml
+homepage: https://github.com/nexmo/api-specification
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Provides Open API Spec 3 definitions for Nexmo APIs
+test_files: []