Open API Project
OneAPI v2.0 Common Information Guide
Document Version 1.0
Document Revision History
Rev #
Date
Description
Author
1.0
June 24 2013
Initial version, based on Aepona
Aepona/Akagi
OneAPI 2.0 Common Information
Kobayashi
Guide doc v1.1a.
Developer Guide
Page 2
© Aepona 2013. All rights reserved.
Copyright
2013
© Aepona Limited,
Beacon House,
Clarendon Dock,
Belfast,
BT1 3BG
All rights reserved. This document or any part thereof may not, without the written consent of
Aepona Limited, be copied, reprinted or reproduced in any material form including but not limited to
photocopying, transcribing, transmitting or storing it in any medium or translating it into any
language, in any form or by any means, be it
electronic, mechanical, xerographic, optical, magnetic or otherwise.
The information contained in this document is proprietary and confidential and all copyright,
trademarks, trade names, patents and other intellectual property rights in the documentation are the
exclusive property of Aepona Limited unless otherwise specified. The information (including but not
limited to data, drawings, specification, documentation, software listings, source or object code) shall
not at any time be disclosed directly or indirectly to any third party without Aepona Limited’s prior
written consent.
The information contained herein is believed to be accurate and reliable. Aepona Limited accepts no
responsibility for its use by any means or in any way whatsoever. Aepona Limited shall not be liable
for any expenses, costs by damage that may result from the use of the information contained within
this document. The information contained
herein is subject to change without notice.
Developer Guide
Page 3
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
Table of Contents
1
What You Will Need - A Summary
2
Developer Access
2.1
Accessing the REST API from a Browser
2.2
Basic Authentication
2.3
Using the REST APIs from a Browser
2.4
Using the REST APIs from an Application
3
Response Codes & Exceptions
3.1
Response Codes
3.2
REST Exceptions
3.2.1
Service Exceptions
3.2.2
Policy Exceptions
Developer Guide
Page 4
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
1
What You Will Need - A Summary
1
The service endpoints made available to you when you registered with your
service provider.
2
The API documentation specific to the APIs you wish to use.
3
Knowledge of an application programming language. Your service provider
may provide you with client libraries and bindings.
4
To receive SMS sent to your application by end users, you will need to obtain a
registrationId (e.g. short code or similar identifier) to identify your application
to the network, which ensures correct routing. For more information on this,
contact your service provider.
2
Developer Access
This section provides the detailed information required to successfully access the services
available to you.
2.1
Accessing the REST API from a Browser
Simply enter the API URL in a browser. At this point you will be prompted to access the
required certificate from the server.
2.2
Basic Authentication
In order to use the various services, basic authentication is required. The information
below is applicable to any of the APIs.
In all cases, if you try to use the service APIs without basic authentication credentials,
you will receive the following HTTP error:
HTTP/1.1 401 Unauthorized
Developer Guide
Page 5
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
2.3
Using the REST APIs from a Browser
Once you have entered the URL into the browser, a pop-up window is displayed which
allows you to enter your username and password. Please enter your application
username and password in order to authenticate.
2.4
Using the REST APIs from an Application
From within a Java application, code similar to the following is required to set up basic
authentication:
import java.net.HttpURLConnection;
Replace “username” and
“password” with your application
import org.apache.geronimo.mail.util.Base64;
username and password.
final static String username = "partner";
final static String password = "partnerpassword";
final static String url = "http://your-endpoint-
here ";
final static String credentials = username + " : "
+ password;
final static String authHeaderValue = new
String(Base64.encode(credentials.getBytes()));
HttpURLConnection con =
(HttpURLConnection)new
URL(url).openConnection();
con.setRequestProperty ("Authorization", "Basic "
+ authHeaderValue);
Developer Guide
Page 6
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
3
Response Codes & Exceptions
3.1
Response Codes
HTTP response codes are used to indicate:
·
200 - Success!
·
400 - Bad request; check the error message for details
·
401 - Authentication failure, check your authentication details
·
403 - Forbidden; please provide authentication credentials
·
404 - Not found: mistake in the host or path of the service URI
·
405 - Method not supported: for example you mistakenly used a HTTP GET to create
an SMS instead of a POST
·
500 - The server encountered an unexpected condition. This could be incorrect
authentication details or limited user permission
·
503 - Server busy and service unavailable. Please retry the request.
For more details on these, refer to http://www.ietf.org/rfc/rfc2616.txt .
3.2
REST Exceptions
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"requestError": {
"serviceError": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": " tel:+016309700000"
}
}}
Developer Guide
Page 7
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
HTTP 400 indicates either a service exception or a policy exception.
The requestError object contains either a serviceException or a policyException
object.
The serviceException describes the reason why the service cannot accept the request;
in this example because the phone number was too long.
A policyException object means that the request syntax is valid, however an operator
policy has been broken, e.g. you are requesting to charge an amount that exceeds a limit
that the operator has set.
serviceException and policyException share the same body, which includes the
following pairs:
· identifier pair - for the exception (messageId)
· text pair - to describe it consistently (text)
· a variables pair - to indicate any specific cause of the error (variables). The variables
relate to the %1 placeholder(s) in the text.
3.2.1 Service Exceptions
The following are some examples of exceptions which may be thrown when an operation
fails:
Table 1: Service Exceptions
Error
Explanation
SVC0001 - Service error
A service-related error has occurred as a result of a
occurred
client invocation on the service. This category can
be used for implementation-specific errors. Contact
the support team.
SVC0002 - Invalid input value
An input parameter value is not of the expected
type. Check the parameter types and re-submit
your request.
SVC0004 - Invalid address(es)
The request terminal device address does not exist.
Update your request and re-submit.
SVC0007 - Invalid charging
The charging information provided is invalid.
information
Update your request and re-submit.
Developer Guide
Page 8
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
SVC0270 - Charge failed
The charge failed. This could be due to, for
example, the transaction not being found or
payment not allowed. Contact the support team.
3.2.2 Policy Exceptions
A policy exception means that the request syntax is valid, however an operator policy has
been broken.
The two types of policy exceptions are as follows:
· POL0002: Privacy Error - There was a problem using the Privacy service. Check your
method use and re-submit your request
· POL0001: Policy error occurred. This exception may be thrown to indicate a fault
relating to a policy associated with the service. This category can be used for
implementation-specific errors such as:
Table 2: Policy Error Codes
Error
Explanation
POL-003: TPA profile not found
The third party application cannot be found.
POL-006: TPA exceeded its
The maximum rate of transactions is exceeded.
maximum allowed rate of
Ensure that the rate of your requests is within the
transactions
limits set up in your SLA, e.g. 10 TPS (Transactions
Per Second).
POL-011: Charging not
Inline charging is not supported by this operator. Re-
supported
submit your request without charging information.
POL-014: White List is enforced,
A white list is enforced and the number is not in the
and address is not in White List
white list. Check your SLA details.
POL-015: Black List is enforced,
A black list is enforced and the number is in the
and address is in Black List
black list. Check you SLA details.
POL-016: Max Requests is
The maximum number of requests for this service is
enforced, and max requests has
exceeded. Contact the support team.
been exceeded
POL-017: Operation is not
The method/operation is not supported in your
allowed
current SLA. Check your SLA and use a method that
is supported.
Developer Guide
Page 9
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
Error
Explanation
POL-018: All targets were
This indicates that none of the destination numbers
rejected for MDN access and
can be retrieved by the internal address resolver
authorization failure
such as LDAP or Lookup.
It includes white/black list rejection when the
destination number cannot be found in either list
that is enforced. In this case, check your policy
contract and request the number to be added
to/removed from the appropriate list.
POL-020: Max Message Length
A maximum message length policy is in place and
is enforced, and max message
you have exceeded this. Check you SLA for the
length has been exceeded
maximum message length, update your message
and re-submit your request.
POL-021: Min Message Length
A minimum message length policy is in place and
is enforced, and message length
your message length is less than this minimum.
is less than min allowed
Check you SLA for the maximum message length,
update your message and re-submit your request.
POL-022: Receipting is
A receipt has been requested but it is not enabled
enforced, and receipting has not
for this service. Remove the receipt request and re-
been enabled
submit you request.
POL-038: Max Charge Amount
A maximum charge amount is enforced and has
is enforced and maximum charge
been exceeded. Check your SLA for this limit and re-
amount has been exceeded
submit your request with the correct amount.
POL-039: Min Charge Amount is
A minimum charge amount is enforced and a value
enforced and charge amount is
less than this has been used. Check your SLA for
less than minimum value
this limit and re-submit your request with the correct
amount.
POL-040: Max Destination
A maximum destination address limit is enforced and
Addresses is enforced and
it has been exceeded. Check your SLA for the limit
maximum destination addresses
and re-submit your request.
has been exceeded
POL-042: The requested
The accuracy requested is too high. Re-submit the
accuracy is less than the
request with a lower accuracy, i.e. a value of 5000m
allowable value
or more.
Developer Guide
Page 10
© Aepona 2013. All rights reserved.
OneAPI v2.0 Common Information Guide
Document Version 1.0
Error
Explanation
POL-049: SPID Black List is
Applicable in multiple carrier deployments, Black List
enforced and address SPID is in
is enforced and the carrier identified by the Service
the SPID Black List.
Provider ID is in the black list. Therefore all the
addresses from the carrier are rejected.
Developer Guide
Page 11
© Aepona 2013. All rights reserved.