nexmo/server-sdk-specification

Nexmo Client Library Guide

server-sdk-specification's Issues

Add details for file downloading via /v1/files to specification

See https://github.com/Nexmo/nexmo-node/issues/85

Add logging to specification

Essential logging for me are:

1. The raw request going from the library to the Nexmo API
2. The raw response coming back from the Nexmo API

These can be invaluable when debugging or when handling support queries.

[Reporting] Required user-agent format is not compatible with spec

In SPECIFICATION.md: "Must set a user-agent with the following format: LIBRARY-NAME/LIBRARY-VERSION/LANGUAGE-VERSION"

This format is not compliant with the RFC7231 spec. Section 5.5.3 states that only NAME/VERSION is supported, not NAME/VERSION/VERSION (or any other variant). Multiple NAME/VERSION values are supported. Compliant example:

User-Agent: nexmo-dotnet/1.0 dotnet/1.0

I ran into this because .NET parses and validates the user-agent string before adding it to the request. It will not allow the string as required in the Nexmo client-library-specification.

Code of conduct template

Any thoughts on adopting a code of conduct for all the libraries?

Examples: http://contributor-covenant.org

Contributing template

README.md template is still lacking content for the Contributing section.

CONTRIBUTING.md template would be useful.

Add proxy support requirement to spec

I've seen this so many times in support and via GitHub requests that making it very clear how to set up a proxy is an essential requirement. We should have a "How to set a Proxy" in the README too.

I'd generally make it part of the initialization for the library. If you can pass in custom HTTP clients then I'd have a standard interface that all custom clients must implement which includes setting a proxy.

Update specification to state libraries should support full JSON structures when generating JWTs

It should be possible to generate a JWT with numerous and nested claims e.g.

{
  "application_id": "dfsdf-sdfsd-sdf-sdfs-dfsfd-dfsdsd",
  "nbf": 1483315200,
  "exp": 1514764800,
  "iat": 1483228800,
  "acl": {
    "paths": {
      "/messages": {
        "methods": ["POST"],
        "filters": {
          "from": "55555555555"
        }
      }
    }
  }
}

Please also note that application_id may not always be a claim.

[Discuss] It should be possible to append additional information to the user agent

If a library uses a Nexmo client library it should be possible for that client to add additional information to the library user agent.

e.g. if the library user agent is nexmo-node/1.0.0/5.0 it should be possible to append information to that. For the Nexmo Command Line interface 1.0 release this may result in the user agent being nexmo-node/1.0.0/5.0/nexmo-cli/1.0.0.

Related: Nexmo/nexmo-cli#38

Should transfer the error message and error code returned by the API

Error response from API’s be translated to language specific error objects with same error codes and messages sent by API

Library Function for Updating account Settings

I Couldn't see a function specified for updating your account settings like drCallBackUrl and moCallBackUrl https://developer.nexmo.com/api/developer/account#settings

Document the correct encoding to use based on what is supported by the API

Encoding on client library requirement should be documented based on the functionality of API. This is to ensure all characters in the text are sent successfully like for ex accented characters, extended characters from GSM Spec and unicode characters.

Is this universal for all entities like sms, voice etc.

Does nexmo API support unicode characters? If yes should the client library encode them in certain characterset? My assumption is to encode all text by UTF-8 only if the incoming text do not contain unicode characters - needs confirmation from the core eng team.