JAMROOM
Communicating with Proxima API endpoints
Table of Contents:
Sending a request to Proxima
Including the App Client Key in your Proxima Requests
-
All Proxima requests must be sent to the proper API endpoint, which depends on the Proxima Service you want to use. For example, all requests to the Proxima User Service would be sent to:
Sending a request to Proxima
http://yoursite.com/api/user
The HTTP Method used would correspond to the ACTION you wish to perform:
POST - Used to CREATE an item
GET - Used to retrieve an individual item as well as list and search items
PUT - Used to UPDATE an existing item
DELETE - Used to DELETE an existing item
So Proxima uses "RESTful" conventions for all communication. Note that Proxima does not adhere 100% to all REST practices, but instead uses the common HTTP methods to basically allow CRUD like applications an easy interface to the Proxima APIs. -
Proxima uses HTTP Basic Authentication for all requests, which means that the the Client Key and the active user's Session ID are sent in clear text to the system. It is important that once you "go live" that you have configured your domain with SSL support, with all Proxima requests being sent over HTTPS - this ensures the security of your user sessions!
-
Including the App Client Key in your Proxima Requests
All requests that are sent to Proxima must include the unique Application Client Key that can be found in your Proxima Core App Browser (Admin -> Proxima Core -> App Browser).
The "Client Key" is used by Proxima to ensure all requests into the system are lined up with the proper Application (Proxima can support as many different applications on the same install as you wish).
The Client Key should be sent as the "username" portion in your HTTP Basic Authentication request. Once a user has been "logged in" (see '(POST) - Login an existing User Account' for details), send the unique Session ID as the password (without a unique session identifier the client is limited to only a set of specific service requests, such as logging in, forgotten password, etc. - see the User Service documentation for the details).
-
In your Proxima App Browser you will see there is also a second key called the Master Key, and this is exactly what it is - if a request is received that is using an application's Master key, all user authentication is bypassed!. So guard your Master Key safely, and only use it for clients that you 100% trust (i.e. a backend server that needs to communicate with your Proxima API endpoints).
