Skip to content

Latest commit

 

History

History
383 lines (290 loc) · 14.2 KB

management-api.md

File metadata and controls

383 lines (290 loc) · 14.2 KB
Raw

SMS Gateway Management API

Back to main page - Table of contents - Previous section - Next section

This API provides functionality to manage messages and receive status from the Gateway. Functionality is divided into functional groups described below. The API is available from web service and REST interfaces, similar to the SMS sending API. It also uses the same triplet of service identifiers (service id, username and password) as explained here.

Interfaces for using the management API

The management API is available as a web service and REST service.

Web service (SOAP over HTTP)

The web service interface is defined by the WSDL and can be retrieved from:

https://[server-address]/mgmt/ws/GatewayManagementV10?wsdl

Error codes

ValueDescription
1000No batch found matching the given customer batch reference for this service In addition the status codes for the SMS Gateway API are also used, e.g., for authorization errors.

REST

The REST interface supports both XML and JSON over HTTP with the following base URI:

https://[server-address]/mgmt/rs/service/{serviceid}

Parameter definition:

TypeNameMandatoryDescription
Path{serviceid}YIdentifies the service to be managed.

Example:

https://[server-address]/mgmt/rs/service/100

Each API documented below defines the URIs used for the request based on this base URI. Use the HTTP Accept header to specify what Content-Type your client prefers for the response. XML (MIME-type: text/xml) and JSON (MIME-type: application/json) are supported.

Note that HTTP Basic authentication (IETF RFC 2617) is used for authentication.

Message batch management

These APIs allow managing batches of messages sent that have been throttled (queued for sending in the Puzzel platform).

Base URI path: /batch/

Resource representations

StoppedBatch

Property nametypeDescription
MessageIdStringUnique message identifier generated by the platform for this message.
CustomerMessageReferenceStringCustomer’s message reference for the message, if given.

MessageBatch

Property nametypeDescription
clientBatchReferenceStringReference name for this batch. Can be used to stop the batch.
totalSizeIntegerNumber of messages left in this batch.
onHoldIntegerNumber of messages on hold in this batch.

Stop batch API

Stop messages that have been throttled or are scheduled to be sent in the future. If sending has started for the batch, only those messages still throttled will be stopped.

Request URI path: /batch/{batch-reference}
Request method: DELETE

Request Parameters

TypeNameMandatoryDescription
Path{batch-reference}YesIdentifies the batch to be managed. Set as the batchReference parameter when sending messages.

Example:
https://[server-url]/mgmt/rs/service/100/batch/my-batch

A request that references batch “my-batch” of service with id 100.

Response Parameters

TypeNameMandatoryDescription
EntityStopBatchResponseYesResponse entity
StopBatchResponse
#ServiceId		YesService id for the response. Same as provided in the request.
StopBatchResponse
#ClientBatchReference		YesClient batch reference for the response. Same as provided in the request.
StopBatchResponse
#StoppedMessages		YesList of messages that were stopped. Other messages in the batch may have been sent. See “StoppedBatch” resource representation above

Response HTTP Statuscodes

Status codeStatus descriptionDescription
200OkRequest executed successfully. See response entity for detailed results.
401UnauthorizedThe pair of username and password given is not authorized to manage the provided service id.
Note that username and password must be provided per the HTTP Basic authentication standard (IETF RFC2617).
404Not FoundThe requested batch cannot be found. Ensure that the batch reference is correct for the given service.
500Internal Server ErrorAn unexpected error has occurred. For example invalid request URI.

Examples

SOAP Webservice Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gwmgmt="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.0">
   <soapenv:Header/>
   <soapenv:Body>
      <gwmgmt:stopBatchRequest>
         <!--You may enter the following 4 items in any order-->
         <serviceId>1000</serviceId>
         <username>Puzzel</username>
         <password>xdyf3bf2</password>
         <clientBatchReference>my-batch-reference</clientBatchReference>
      </gwmgmt:stopBatchRequest>
   </soapenv:Body>
</soapenv:Envelope>
SOAP Webservice Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:stopBatchResponse 
           xmlns:ns2="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.0">
         <serviceId>27</serviceId>
         <clientBatchReference>my-batch-reference</clientBatchReference>
         <stoppedMessages>
            <messageId>6z02r0001500</messageId>
         </stoppedMessages>
         <stoppedMessages>
            <messageId>6z02r0001600</messageId>
         </stoppedMessages>
         <stoppedMessages>
            <messageId>6z02r0001700</messageId>
         </stoppedMessages>
      </ns2:stopBatchResponse>
   </soap:Body>
</soap:Envelope>
REST Request
DELETE /mgmt/rs/service/1000/batch/my-batch-reference HTTP/1.1
Host: smsgw.intele.com
Authorization: Basic aW50ZWxlY29tOnhkeWYzYmYy
User-Agent: curl/7.26.0
Accept: application/json

Notice that this example uses the Accept-header to request “application/json” used as the response content type. Also notice the usage of HTTP Basic authentication for service authentication and authorization.

REST Response
HTTP/1.1 200 OK
Date: Thu, 16 Jan 2014 13:22:13 GMT
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "serviceId":1000,
  "clientBatchReference":"my-batch-reference",
  "stoppedMessages":[
    {"messageId":"6z02r0001200","clientMessageReference":null},
    {"messageId":"6z02r0001300","clientMessageReference":null},
    {"messageId":"6z02r0001400","clientMessageReference":null}
  ]
}

Batch list API

Retrieve list of batches to be sent including their size and state (waiting to be sent or on hold). If sending has started for the batch, only those messages still throttled will be reported.

Request URI path: /batch/	
Request method: GET

Request Parameters

N / A

Response Parameters

TypeNameMandatoryDescription
EntitygetBatchListResponseYesResponse entity
ListmessageBatchYesList of message batches for this service. See “MessageBatch” resource representation above

Response HTTP Statuscodes

Status codeStatus descriptionDescription
200OkRequest executed successfully. See response entity for detailed results.
401UnauthorizedThe pair of username and password given is not authorized to manage the provided service id.
Note that username and password must be provided per the HTTP Basic authentication standard (IETF RFC2617).
404Not FoundThe requested batch cannot be found. Ensure that the batch reference is correct for the given service.
500Internal Server ErrorAn unexpected error has occurred. For example invalid request URI.
SOAP Webservice Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns: gwmgmt ="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <gwmgmt:getBatchListRequest>
         <!--You may enter the following 3 items in any order-->
         <serviceId>1000</serviceId>
         <username>Puzzel</username>
         <password> xdyf3bf2</password>
      </gwmgmt:getBatchListRequest>
   </soapenv:Body>
</soapenv:Envelope>
SOAP Webservice Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getBatchListResponse xmlns:ns2="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.1">
         <messageBatch>
            <clientBatchReference>gwmgmt-test</clientBatchReference>
            <totalSize>3</totalSize>
            <onHold>1</onHold>
         </messageBatch>
      </ns2:getBatchListResponse>
   </soap:Body>
</soap:Envelope>
REST Request
GET /mgmt/rs/service/1000/batch/ HTTP/1.1
Host: smsgw.intele.com
Authorization: Basic aW50ZWxlY29tOnhkeWYzYmYy
User-Agent: curl/7.26.0
Accept: application/json

Notice that this example uses the Accept-header to request “application/json” used as the response content type. Also notice the usage of HTTP Basic authentication for service authentication and authorization.

REST Response
HTTP/1.1 200 OK
Cache-Control: max-age=60, private
Content-Encoding: gzip
Date: Thu, 16 Jan 2014 13:22:13 GMT
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "messageBatch":[
    {
      “clientBatchReference” : “my-batch-reference",
      “totalSize” : 1000,
      “onHold” : 0
    },
    {
      “clientBatchReference” : “another-batch",
      “totalSize” : 200,
      “onHold” : 0
    },
    {
      “clientBatchReference” : “discount-notification",
      “totalSize” : 30000,
      “onHold” : 0
    }
}

Batch status API

Status for a single batch, including total size and state (waiting to be sent or on hold). If sending has started for the batch, only those messages still throttled will be reported.

Request URI path: /batch/{batch-reference}
Request method: GET

Request Parameters

TypeNameMandatoryDescription
Path{batch-reference}YesIdentifies the batch to be managed. Set as the batchReference parameter when sending messages.

Example:
https://[server-url]/mgmt/rs/service/100/batch/my-batch

A request that references batch “my-batch” of service with id 100.

Response Parameters

TypeNameMandatoryDescription
EntitygetBatchStatusResponseYesResponse entity
getBatchStatusResponse#messageBatch
#ServiceId		YesMessage batch. See “MessageBatch” resource representation above.

Response HTTP Statuscodes

Status codeStatus descriptionDescription
200OkRequest executed successfully. See response entity for detailed results.
401UnauthorizedThe pair of username and password given is not authorized to manage the provided service id.
Note that username and password must be provided per the HTTP Basic authentication standard (IETF RFC2617).
404Not FoundThe requested batch cannot be found. Ensure that the batch reference is correct for the given service.
500Internal Server ErrorAn unexpected error has occurred. For example invalid request URI.

Examples

SOAP Webservice Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns: gwmgmt ="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <gwmgmt:getBatchStatusRequest>
         <!--You may enter the following 3 items in any order-->
         <serviceId>1000</serviceId>
         <username>Puzzel</username>
         <password> xdyf3bf2</password>
         <clientBatchReference>my-batch</clientBatchReference>
      </gwmgmt:getBatchStatusRequest>
   </soapenv:Body>
</soapenv:Envelope>
SOAP Webservice Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getBatchStatusResponse xmlns:ns2="http://chimera.intele.com/gw/wsdl/GatewayManagement-v1.1">
         <messageBatch>
            <clientBatchReference>my-batch</clientBatchReference>
            <totalSize>3000</totalSize>
            <onHold>100</onHold>
         </messageBatch>
      </ns2:getBatchListResponse>
   </soap:Body>
</soap:Envelope>
REST Request
GET /mgmt/rs/service/1000/batch/my-batch HTTP/1.1
Host: smsgw.intele.com
Authorization: Basic aW50ZWxlY29tOnhkeWYzYmYy
User-Agent: curl/7.26.0
Accept: application/json

Notice that this example uses the Accept-header to request “application/json” used as the response content type. Also notice the usage of HTTP Basic authentication for service authentication and authorization.

REST Response
HTTP/1.1 200 OK
Cache-Control: max-age=60, private
Content-Encoding: gzip
Date: Thu, 16 Jan 2014 13:22:13 GMT
Content-Type: application/json
Connection: close
Transfer-Encoding: chunked

{
  "messageBatch":{
      “clientBatchReference” : “my-batch",
      “totalSize” : 3000,
      “onHold” : 100
    }
}