Navigation
- index
- modules |
- next |
- previous |
- Lastline API »
Authentication¶
The Lastline API supports account-based authentication.
Since the API is always accessed over https, the authentication parameters are never sent in clear-text and can be sent using unencoded ASCII text.
Account-Based Authentication¶
For account-based authentication, all Lastline API methods require two parameters:
- username: Lastline portal account username
- password: Lastline portal account password
Authentication Methods¶
To explicitly authenticate with the API, a client can send credentials to the
login()
method. In addition to the response code, the API returns a
session cookie which must be included in all subsequent requests to the API.
Alternatively, if any non-authentication method is called without the required session cookie, the client can include credentials directly as parameters to the called API method. The API will validate credentials and, if authentication was successful, forward the request to the originally called method and include the session cookie in the response of the called method.
Therefore, all methods in the Lastline API accept the authentication credentials as parameters and can return authentication-related error codes. These parameters and error codes are excluded from the documentation of the individual API methods.
Quick-Start¶
To test your Lastline API credentials, you will need to make an HTTP POST request to the login
API method, providing your username and password as form parameters. As an example, this can be
achieved as follows using the curl
command-line utility:
curl -X POST "https://user.lastline.com/papi/login" -d "username=USERNAME&password=PASSWORD"
This will authenticate using your account, providing an output similar to the example shown below:
{"success": 1, "data": "true"}
The session cookie obtained from the login API request can be used to perform further API calls,
as demonstrated by the following example, once again using the curl
utility:
curl -X POST "https://user.lastline.com/papi/login" -d "username=USERNAME&password=PASSWORD" -c lastline-cookie
curl -X POST "https://user.lastline.com/papi/ping" -b lastline-cookie
Here, the ping()
API method was used as a test, and should output:
{"success": 1, "data": "pong"}
Method Index¶
Method Documentation¶
-
authentication.
login
(response_format)¶ Authenticate with the API.
URL
/papi/login[. response_format]
response_format can be xml or json (defaults to json)
HTTP METHOD
GET or POSTGET/POST Parameters
- username:
Lastline portal username. (required)
- password:
Lastline portal password. (required)
Contents of successful response
“true”Error Codes
LLAPI_ERROR__AUTHENTICATION_ERROR
:Invalid credentials were provided.
LLAPI_ERROR__PERMISSION_DENIED
:Permission denied.
-
authentication.
logout
(response_format)¶ Destroy authenticated session.
URL
/papi/logout[. response_format]
response_format can be xml or json (defaults to json)
HTTP METHOD
GET or POSTContents of successful response
“true”
-
authentication.
ping
(response_format)¶ Validate authenticated session.
URL
/papi/ping[. response_format]
response_format can be xml or json (defaults to json)
HTTP METHOD
GET or POSTContents of successful response
“pong”
Response Format¶
The format of API responses can be selected by appending an extension to the request URL. Supported formats are JSON and XML. If no extension is provided, the format defaults to JSON. JSON is the recommended format for automated processing, while XML is recommended for human consumption (since modern browsers make it readable by pretty-printing it).
A successful response comes in the form:
{"success": 1, "data": ...}
A failed response will return:
{"success": 0, "error_code": <ERROR_CODE>, "error": <ERROR_MESSAGE>}
The error_code field is optional.
Timestamps¶
By default, timestamps returned by the Lastline API are in UTC. Specific
APIs accept timezone
/time_zone
as parameters. In such cases,
all returned timestamps are converted into the requested timezone. Support
for timezone
/time_zone
is documented in the respective APIs.
Error Codes¶
The Lastline API uses error-codes for reporting errors. Errors related to authentication or general mis-use of the API are documented below. Additionally, each API module provides error-codes for module-specific errors.
-
LLAPI_ERROR_UNSUPPORTED_FORMAT
¶ Error code 1: Returned when requesting an unsupported API format.
-
LLAPI_ERROR_NO_DATA_FOUND
¶ Error code 2: Generic error returned when requesting data that is (currently) not available.
-
LLAPI_ERROR__AUTHENTICATION_ERROR
¶ Error code 3004: Returned when requesting results with invalid credentials.
-
LLAPI_ERROR__PERMISSION_DENIED
¶ Error code 3001: Returned when requesting a resource that the user or license is not permitted to access.
-
LLAPI_ERROR__INVALID_PARAMETER
¶ Error code 3005: returned when sending a request with an invalid parameter.
-
LLAPI_ERROR__MISSING_PARAMETER
¶ Error code 3006: returned when sending a request that is missing a required parameter.
-
LLAPI_ERROR__NO_SUCH_ENTITY
¶ Error code 3007: returned when requesting an entity that does not exist.
-
LLAPI_ERROR__DUPLICATE_ENTITY
¶ Error code 3008: returned when trying to add an entity that conflicts with an already existing entity.
-
LLAPI_ERROR__CUSTOMER_SHARD_NOT_FOUND
¶ Error code 3009: returned when trying to access a customer shard that does not exist.
-
LLAPI_ERROR__UNSUPPORTED_FEATURE
¶ Error code 3010: returned when an operation is requested on an appliance that does not support the feature.
-
LLAPI_ERROR__ENTITY_NOT_IN_STORAGE
¶ - Error code 3011: Returned when attempting to access an
- entity that is not available in storage. This could indicate that entity was deleted by data retention or was not persistently stored in the first place.
-
LLAPI_ERROR__ENTITY_IN_USE
¶ Error code 3012: returned when interaction with an entity is blocked because it’s being used.
-
LLAPI_ERROR__NOT_YET_AVAILABLE
¶ Error code 3013: returned when requesting an entity that is not yet created or processed.
-
LLAPI_ERROR__TOO_MANY_REQUESTS
¶ Error code 3014: returned when the user or license has momentarily exceeded the allowed number of accesses.
-
LLAPI_ERROR__HOSTED_BACKEND_UNVAILABLE
¶ Error code 3015: returned when an on-premise API instance temporarily fails to reach the hosted API instance requested.
-
LLAPI_ERROR__PASSWORD_REQUIRED
¶ Error code 3016: returned when trying to perform an operation without providing the required password.
-
LLAPI_ERROR__DUPLICATE_OPERATION
¶ Error code 3017: returned when trying to perform an operation that has already been executed.
-
LLAPI_ERROR__TEMPORARILY_UNAVAILABLE
¶ Error code 3018: Returned when the request cannot be satisfied due to a temporary issue.
-
LLAPI_ERROR__WRONG_DATACENTER
¶ Error code 3019: Returned when a request to Lastline’s hosted backend infrastructure was sent to the wrong data-center. Client should submit the request to the correct datacenter instead.
Navigation
- index
- modules |
- next |
- previous |
- Lastline API »