Representational state transfer (REST) or RESTful Web services are one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.
Primal Connect API is a Restful API which is built over lightweight REST framework Spark, embedding famous Jetty web server, and provides company or individual developer ability to send and receive Text and MMS over internet.
In order to use Primal Connect API, first, you have to sign up. Afterwards login to receive your Token and send a message.
Primal Connect API uses four HTTP methods when accessing API resources: GET, POST, PUT and DELETE. The HTTP GET method is used to retrieve (or read) a representation of a resource such as account, SMS, MMS. The PUT method is used to update an existing resource. The POST method is used to create new resources.
Primal Connect API responses all data in JSON format, and requires the HTTP content data in JSON format as well.
Primal Connect API works with a token to secure authentication. You can generate a token from Primal Connect dashboard.
To use the Token, you must put the following into the header for each API call.
token: <token>
Token is generated from Skynet, it is global unique 40-character token.
Example:
The following are examples of HTTP error codes that the API will generate when a correctly authenticated request fails: 400 - The request was formatted incorrectly, or one of the required fields contains invalid data 401 - Authentication failed or the user does not have permission to access the requested resource. 403 - The user is attempting to perform an action/request that is not allowed. 404 - The requested resource was not found. 405 - The requested method is not supported. 429 - Too many requests. 500 - General error or it is an unexpected error. Other response codes include: 200 - Everything worked correctly. 201 - Everything worked correctly and public ID or location of the new resource is returned.
Sending SMS with HttpClient
1. Download Apache HttpComponents
2. Create HttpClient and HttpPost request
3. Set Request Entity: JSON format
4. Execute Request
5. Print Response Code
6. Print Results
In order to receive the replied SMS to your application, you need visit Primal Skynet to set up your application callback URL and Method. For example: POST http://yourcomapny.com/ GET http://yourcompany.com/
The SMS message is delivered in POST content with JSON format:
The SMS message is appended into GET method as querying parameters:
Note: text in query parameter is percent encoding (also called URL encoding).