Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

Overview

The Flex5 REST API is in an early access stage and under heavy development & evolution. This is our "private" API that is being built to service our Flex5 Phone, Tablet, & Desktop applications.

It is very likely we will build a "public" API layer in the future with something like GraphQL. The reason is that this REST API is low-level, with a flat JSON structure. This means you will have to make a lot of individual API calls to gather all the data you need.

We envision a more public-friendly API in the future that allows external developers to better fetch & aggregate data in a single request.

API Terms & Conditions

Since this API is under heavy development & evolution (and could get replaced with a "public" API someday), we require that you sign off on an API Terms & Conditions document; you can find it here.

Download that document, fill it in, sign it, then go here to complete a request form. Once the request is received, we will review it, and if approved, we will provide you with a special "source" property which is needed to get authentication tokens.

Accessing Your Own API Documentation

Our API Documentation tool is Swagger UI. You can browse your own Swagger UI by using the template URL below.

Substitute in your own subdomain for "yourflexsite": https://yourflexsite.flexrentalsolutions.com/f5/swagger-ui.html

You can download the entire Swagger API definition by right-clicking the link below API Documentation (near the top of the screen) and using your browser's "Save As" feature. The link should look like https://yourflexsite.flexrentalsolutions.com/f5/api/api-docs.

An Authentication Example With The Flex5 Dev API

You can browse the cutting edge API's from Flex Dev here: https://flex5dev.flexrentalsolutions.com/f5/swagger-ui.html

First, let's get an Authentication Token by going to the above URL, then click Authentication and Try It Out. Replace the Example Value information (username/password/source) with that which you receive in response to sending the signed terms & conditions document.

The JSON should look something like the below. Notice the special "source" property, which is a special "key" that prevents unauthorized access to the API.

{
  "username": "api-test",
  "password": "password",
  "source": "<will be provided>"
}

Next, click the Execute button. This will return a JSON response that looks something like below. Notice the "token" property. That is your authentication token. Copy that token and save it in a safe place.

{
  "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAOVWTY_TMBD9LzkXq7vqUtobEhcOiL3ABXFw7WkyrGMHj5NuF_HfmaQfcbdOGsSRQxXVHr95fm9mkl8Z1ZtsnckK3wSgkM0y5UEG0Nn67mFxt1yuFvPVYjmfZQGstOEjb2RbA88PGhqOrsCXSITOUrb-1v0VlXc_QAUSDcLuGCO2yMcVSkPCg5JGXRwWaBuwwfl9fOi4p5wHURP497pEewJU_CullTkMIUUpYybtQQ0Gwumg2OCLq4h5o0KbJxj0mPBcOR_AX-63a9J0D8a9oHkWQztl63IDXrgGvEcNCWlSF1IlsQSW9Q9fmdnr3D23UqLtXFIp6LFbDTE4KYMlr1EsoIzueA3nvAJBRavKsD2jHoDGEOcjsIQBGxiqD1VIm8OjJNo5rxP3TyLEATLPPeQyMGQK_-DAp06etP1G7l194X7CooS_LTztKZb0JIfyTJm7JS3FjWoZ48or5Kw0-BJfuMMfELh0ujZwiRnLFzt2LnpmssX8ajmKvZJIudpeNVi_nXtXVzcan5QcdGDj3Y5AFKg1DAYdikn8rHnisdTn0k8MKx9qlrPNyMZ47K06Oti7RSC9KkRwT7yU7rOh4Lhi-4ES9884M2nMgDXdw6AKPJXJGZ5M0-7KiGK4zKXWwiYocyWD1dLf8C-RiRtrvKfETnooHL8m2nRlFShZwxs08Ij2c9VW_dms65gP0GA_Rtu24LHytDVux0KVPMEF8Lg19BfNFSeRdSiYPrc2v2q_UN9Q_1wI0w2eaMuQKFN0nSzctHfHyKD_f3T7Psv4I-Twefbu_v7tfPX7D4ARUHjGCQAA.tgbY7Wsje-qyiP99xfXSGtJ3-3JBOhpJUGnSRbwcsshrOIwbrEy7LcoQ7NSI4INxhyWo6hV6V3KzXyYE6uniqA",
  "user": {
    "id": "3820fee0-5fa1-11e8-bc43-12aef1b28bdc",
    "name": "Api Test",
    "userName": "api-test",
    "emailAddress": "api-test@flexrentalsolutions.com"
  }
}

In Swagger, there is an Authorize button in the top right. Copy the token property, click the Authorize button, paste it in the Value field and click the next Authorize button. Now you are logged in and can begin to play around with the other endpoints inside Swagger UI.

Note: you will need to repeat this process for your own URL. Also, note that your Flex site will only show the currently available public APIs which will differ from the flex5dev offerings.


Writing Your Own Code

When you write your code against the API, the process will be similar. You'll have to post to the authentication endpoint to get a token and then send it down in the X-Auth-Token header for ALL requests.

If your token has aged approximately 1 hour, the server will kick out a refresh token in the X-Auth-Token-Refreshed header. Our app just sniffs for the refresh token on each request, and if it finds one, it replaces the current one and starts sending the new one.

A Flex Api token lasts approximately 12 hours and then expires. You should cache the token somewhere safe and sniff for a new token on every request. Replace the existing token when you see a new one.

If you had a long period between requests and your token has expired, you'll get a 401 UNAUTHORIZED. You can detect that, and send a new /auth request to get a new token.

  • No labels