Emnify API

Emnify API

Publisher: Search Engine (Ursa)
Base URL: http://blog.acme.com

The EMnify Service Core implements a RESTful API. Communication with the API is done over HTTP(S) requests with JSON body content and content-type "application/json" with an authentication token as a requirement for every API call. All API calls must be made over https.

## Authenticating the API

Initial authentication against the API is done by providing user credentials, the API then returns a token that must be used in all future API calls in the header of the HTTP request as "X-Auth-Token".

The access token will be valid for a certain time period and expire after that, the user will need to re-authenticate then to get a new access token in that case.

For access from applications special access tokens are available that do not expire.

All API calls including the Authentication must be made over secure socket (SSL).


## URL format

All API URLs are following a generic structure like

/api/APIVERSION/ENDPOINT/{object_id}

e.g.

/api/v1/user/123

Also some resources may provide access to further sub-resources

/api/v1/user/123/tracking

## HTTP verbs

While the API URLs represent the different resources you can work with, you can perform actions on them through different HTTP verbs.

* GET - retrieves a representation of a resource without side-effects (nothing changes on the server)

* HEAD - retrieves just the resource meta-information (headers) i.e. same as GET but without the response body - also without side-effects

* OPTIONS - returns the actions supported for specified the resource - also without side-effects

* POST - creates a resource

* PUT - (completely) replaces an existing resource

* DELETE - deletes a resource

* PATCH - sax

For HTTP clients that only support POST and GET the method can be alternatively transmitted in the "X-HTTP-Method-Override" header.

## HTTP Headers

Each HTTP request must have at least the following headers:

* Content-Type: application/json

* Accept: application/json

* X-Auth-Token: Access token as received during authentication

## HTTP Return codes

Code | Description
------------- | -------------
200 OK | Response to a successful GET, also used for a POST if it does not result in a creation
201 Created | Response to a POST that results in a creation, usually will return a Location header pointing to the location of the new resource
204 No Content | Response to a successful request that is not returning a body
400 Bad Request | The request is malformed, e.g. the body cannot be parsed
401 Unauthorized | No or invalid access token provided
403 Forbidden | Access token is valid, but user has no access permissions to the request resource
404 Not Found | A non-existent resource is requested
405 Method Not Allowed | HTTP method being requested isn't allowed
410 Gone | Indicates that the resource at this end point is no longer available.
415 Unsupported Media Type | Incorrect content type was provided as part of the request
422 Unprocessable Entity | Body will return list of validation errors
429 Too Many Requests | Request is rejected due to rate limiting

## Error Handling

The API will return HTTP error codes according to the type of the error, 400 error codes are used for client related issues, 500 error codes for server side issue.

### JSON error representation

400 error codes come with a consumable JSON error representation:

{
"error_code" : 1000,
"error_token" : "InvalidAccessToken"
"message" : "XYZ failed",
"description" : "Here comes a detailed description of the error."
}

Some error codes like ValidationFailed can contain multiple error messages embedded

{
"error_code" : 1005,
"error_token" : "Failed",
"message" : "Input validation failed",
"description" : "Here comes a detailed description of the error.",
"errors" : [
{
"error_code" : 2000,
"error_token" : "InvalidUsername",
"field" : "username",
"message" : "Username must be a valid email address"
},
{
"error_code" : 2001,
"error_token" : "InvalidOrganisationID",
"field" : "organisation_id",
"message" : "Organisation ID cannot be blank"
}
]
}

### List of Error Codes

#### Generic Error Codes

Code | Description
------------- | -------------
1000 | InvalidAccessToken
1001 | AuthenticationFailed
1002 | ValidationFailed
1003 | UnknownUsername
1004 | DuplicateUsername
1005 | UnknownUserID
1006 | UnknownEndpointID
1007 | UnknownServiceProfileID

#### Validation Error Codes

Code | Description
------------- | -------------
2000 | InvalidUsername
2001 | InvalidOrganisationID


Available Platforms


DISCLAIMER: These SDKs are generated using publicly available descriptions of APIs that anyone has created. As such there are no guarantees for any of the SDKs below, or that this listing is maintained by or even related to the company it claims to be, unless explicitly specified.

C-Sharp


Portable Class Library Download Customise

A project for creating a C# class library (.dll) that can run on Windows, Silverlight and Windows Phone.

Download Documentation | View Older Versions

Objective-C


Cocoa Touch Static Library Download Customise

A foundation framework based template for building static library in Objective-C.

Download Documentation | View Older Versions

Java


Android Library (Gradle) Download Customise

A gradle based android library project, which can be used with Android Studio as well as command line based gradle build system.

Download Documentation | View Older Versions

Java Library (Eclipse) Download Customise

An eclipse based java library project, which can be used with JRE7.

Download Documentation | View Older Versions

Javascript


Angular JS Download Customise

An AngularJS library based on v1.3.0.

Download Documentation | View Older Versions

Node.js Download Customise

A Node.js npm package based on Node.js v0.12.4

Download Documentation

PHP


PHP Library Download Customise

A php library based on PHP >= 5.3 and Composer dependency manager

Download Documentation | View Older Versions

Python


Python Library Download Customise

A Python library based on Python 2.7, that uses PIP as the dependency manager

Download Documentation | View Older Versions

Ruby


Ruby Gem Download Customise

A Ruby Gem based on Ruby >= 2.0.0

Download Documentation | View Older Versions

Go


Go Library Download Customise

Go language (v1.4), client library package that is compatible with command line tools as well as the Goclipse IDE.

Download Documentation

All Reviews (0)


There are no reviews at the moment.

Users of this SDK (0)


There are no uses at the moment.

Rating

No Rating

Category

Other

Tags

No Tags