Join us in San Francisco on the 29/30th of October for two days of developer workshops and technical talks

Contributing Code Examples

Nexmo Developer hosts many code examples, and endeavours to make them as consistent as possible. You should follow this guide when contributing code examples to the code snippets repositories or directly to Nexmo Developer.

Use the library

If an existing Nexmo-supported API library supports the functionality, you should use that library for code samples.

Principle of Least Astonishment

Code samples should match the expectations and experience of a median-level competent developer in a language and try hard to not surprise or confuse them. Code samples for APIs are not a place to use flashy, experimental or cutting-edge techniques, but to try to maximise compatibility, and reduce ambiguity.

Code samples MUST NOT use any technique widely considered to be insecure, badly designed or likely to cause harm or confusion to the user.

Placeholders

The following values should be used as placeholders in code examples. They can be specified assigned as constants out of the range of view of the rendered code to allow the code to be executed whist providing an obvious placeholders for the reader.

Key Description User customisation (future)
NEXMO_API_KEY The users Nexmo API Key
NEXMO_API_SECRET The users Nexmo API Key
NEXMO_NUMBER The virtual number that the user holds with Nexmo
TO_NUMBER for outbound

YOUR_NUMBER for inbound
The number that the user owns or wants to communicate with
NEXMO_APPLICATION_PRIVATE_KEY Represents a string of the actual private key
NEXMO_APPLICATION_PRIVATE_KEY_PATH Represents a string that relates to the private key directory

See also: our replaceable values listed in the writing style guide.

Future auto-magical user customisation

In the future we will customise code examples to the logged in user for example by adding API key and secret to the examples. To do this we need to be careful about how we use placeholders.

Good

This input:
const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET
})
Or this input:
const nexmo = new Nexmo({
  apiKey: 'NEXMO_API_KEY',
  apiSecret: 'NEXMO_API_SECRET'
})

Would be converted to this into something like:

const nexmo = new Nexmo({
  apiKey: 'abc123',
  apiSecret: 'abcdef123456789'
})

❎ Bad

This input:

NEXMO_API_KEY = process.env.NEXMO_API_KEY
NEXMO_API_SECRET = process.env.NEXMO_API_SECRET

// Something else

Would be converted to this invalid example:

'abc123' =  process.env.'abc123'
'abcdef123456789' = process.env.'abcdef123456789'

// Something else

SMS Specific

Message Body

A test SMS sent [demonstrating <feature>] using  the Nexmo SMS API

SenderID

Acme Inc

Webhooks

The following URL paths should be used in examples that use Webhooks.

Path Description
/webhooks/answer The application answer event URL
/webhooks/event The application event event URL

Example code should always accept query string parameters for GET and POST requests.

Example code should always accept JSON for POST requests.

NCCO examples

Below you can find static NCCO's that can be used in code examples. The source of these can be found in the /public/ncco directory of Nexmo Developer.

Example URL
Basic text-to-speech https://developer.nexmo.com/ncco/tts.json

Code

Length

Where possible code should be kept to a maximum of 80 characters per-line.

The capacity before scrolling occurs is 101 characters however not all code examples are as wide as this.

----------------------- I am a line with 80 characters ------------------------
--------------------------------- I am a line with 101 characters ----------------------------------

Code blocks

Normal code blocks are specified using three backticks at the start and end.

This is a normal code block.

It does not specify a language so is not syntax highlighted.

Here is some Ruby:

def print_hi(name)
  puts "Hi #{name}"
end

print_hi('Adam')
#=> prints 'Hi Adam' to STDOUT.

Tabbed examples

Tabbed examples via the use of the tabbed_examples construct should no longer be used. Instead use code snippets.

Note: There are two formats of the tabbed_examples construct in current use, both of which are now deprecated.

Linters, Formatters & Code Style Guides

Code throughout Nexmo Developer should be consistent. To help achieve this code examples should be tested with the following tools and against guides on their default configuration:

Language Resource Configuration
Node Standard JS Non configurable
Java - -
.NET - -
PHP PHPCS PSR-2
Python YAPF Default
Ruby Rubocop Default

Languages

JavaScript

Documentation should be clear whether JavaScript code is intended to run on the server (using, say, node.js), the client, or both.

Python

Avoid code that is significantly different in Python 2 and 3. When this is unavoidable, abstract away the incompatible code to the smallest area possible and use __future__ to ensure backwards compatibility with Python 2.

Inbound HTTP calls should use a WSGI-compatible web framework, preferably the Flask micro-framework. Explanations of how to integrate Nexmo APIs with Django are sensible too.