— title: Code Examples
navigation_weight: 4¶ ↑
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¶ ↑
{column:1/2} This input:
const nexmo = new Nexmo({ apiKey: NEXMO_API_KEY, apiSecret: NEXMO_API_SECRET })
{end} {column:2/2} Or this input:
const nexmo = new Nexmo({ apiKey: 'NEXMO_API_KEY', apiSecret: 'NEXMO_API_SECRET' })
{end}
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 | 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.