First steps – OKAPI:Orbits

Veröffentlicht5. July 2019

Last Updated On9. January 2020

VonChristopher

Scope: This introduction shall give you an overview, of how to access our prototype from the terminal. If you never dealt with REST API calls, we recommend going through this step by step. If you are familiar with REST already or if you just want to use OKAPI without looking at the details, you probably want to look at our API documentation and connectors (for Matlab and Python). Using those simplifies the API use, as it takes over all REST-API communications. Note that this description is available for bash (on Linux and macOS) and Powershell (for windows users).

Prerequisites: Before going though this tutorial, make sure that you have a demo (or any other) account. The version for which this tutorial was created is v2020.01. Furthermore, you need to have wget installed for your terminal of choice (in powershell on windows, wget is an alias for the Invoke-WebRequest cmdlet , so it should be available). It furthermore is recommended to install jq if you are running your tests from bash. This tool helps you handling json objects.

Our software is accessible via a REST API. This means that you can communicate with it via http commands. Currently supported are POST and GET methods. Send a POST request to our server to start a calculation. Once the calculation is done, the results are collected by sending a GET request. In this tutorial, we will go through the process step-by-step, using wget for the communication. As example, we will use the pass-prediction functionality.

BASH (Linux/macOS)

Before getting started, one last recommendation: While it is possible to run the commands inline, we recommend you to paste them one-by-one into a shell script! This will facilitate all future requests and furthermore make debugging much easier. Furthermore, some of the operations are time critical to a certain degree. When embedded in a script, you do not have to worry about that. If you prefer reading to writing yourself, the code that is to be created in this tutorial can also be found here.

1. Authentication

To be able to use OKAPI, you have to authenticate. We use services from Auth0 for that. Therefore, before being able to send any requests to our server, you have to get a token from Auth0. This token is received by sending a HTTP POST request to Auth0. As every HTTP request, it contains a header, and a body. When using wget, it is most easy to send the body as a file. Depending on the programming language you will work with in the future, you can use build-in data types for that (for example structs in Matlab, or dicts and lists in Python). The body file to send an authentication request to Auth0 looks as follows:

{
    "grant_type":"password",
    "username": "<your_username_as_string_in>",
    "password": "<your_password_as_string_in>",
    "audience": "https://api.okapiorbits.space/picard",
    "client_id": "jrk0ZTrTuApxUstXcXdu9r71IX5IeKD3",
    "scope": <requested_scopes_as_strings_in_"_">
}

Create a file like this using an editor of your choice and save it (for example under the name authentication_request.json). Insert your password and username. For the scope you can currently put any string, but make sure that you do not omit that field. Now, you are ready to send the request to the server:

wget --server-response --quiet --body-file=authentication_request.json --output-document=token.json --header="content-type: application/json" --method=POST https://okapi-development.eu.auth0.com/oauth/token

You see that the request is split into the body (make sure to use your filename) and the header. In the header you only need to define the content-type. Furthermore, you tell wget where to save the output. As we want to use the token afterwards, it makes sense to save it to a file (for example token.json). Now execute the command and inspect the response. It should contain the statement[il] HTTP/1.1 200 OK [/il]. The token that is returned should look like the following:

{
    "access_token": "<very_long_string_with_token>",
    "scope": "<string_with_your_scopes>",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Important in here are the scope and expires_in fields: In the first, all the endpoints you have access to are defined. If you have requested the Demo account, you have full access to all available endpoints for a duration of 30 days. After that, the endpoints depend on your plan. The Free plan will give you access to every endpoint necessary in this tutorial. The second field tells you how long the token is valid in seconds. Current standard is 86400 seconds ( = 1 day). After that, you would have to get the token again. If you are using OKAPI frequently, you could just create a recurring job (for example using cronjob), which refreshes your token automatically once per day.

2. Sending the first request

Now you have finished the authentication, so you are ready to send your first request. Using wget, the command looks as follows:

ACCESS_TOKEN_VALUE=`cat token.json | jq --raw-output .access_token`

wget --content-on-error \
     --output-document=request_response.json \
     --body-file=pass_prediction_request.json \
     --header="Content-Type: application/json" \
     --header="Accept: application/json" \
     --header="access_token: ${ACCESS_TOKEN_VALUE}" \
     --method=POST \
     http://okapi.ddns.net:34568/predict-passes/sgp4/requests

sleep 3

The first line in there is a “short-cut”, to get the token from the token.json file. For this, you read the content from that file, pipe it to the jq programm which returns the content of the field access_token into the variable ACCESS_TOKEN_VARIABLE. Note the “ around the command! The second line is the actual request. It is very similar to the command to retrieve the access token: Again, you define a body (given as a file, we address this in a bit) and the header. This time, the header needs to know the content-type and the accept value. Furthermore, you include the access token, which is why we copied it into the variable (if you are unable to use jq, you have to copy-paste the value of the access token into the request). This time, instead of using the GET method we use POST. The request is send directly to OKAPI, using the endpoint for pass-prediction requests. Also as before, the response from the server is written to an output file, which we call request_response.json. The sleep is included in the command to give the server a moment to process the request before you continue (which is important during the next step).

Now, the last thing that is needed is to provide input on the pass prediction you actually want to perform. In the command stated above, the request is defined in the file pass_prediction_request.json and looks as follows:

{
    "tle":"1 25544U 98067A   18218.76369510  .00001449  00000-0  29472-4 0  9993\n2 25544  51.6423 126.6422 0005481  33.3092  62.9075 15.53806849126382",
    "simple_ground_location":{
        "longitude":10.645,
        "latitude":52.3283,
        "altitude":0.048
    },
    "time_window":{
        "start":"2018-08-06T18:19:44.256628Z",
        "end":"2018-08-07T00:00:00.000Z"
    }
}

Note that the current version requires you to insert a TLE to describe the satellite’s orbit. Future releases will support a much larger variety of inputs formats. You have to keep the format exactly as described above. The location of the ground station is given in WGS-84 coordinates. Longitude and latitude are given in degree, the altitude in km. OKAPI will return all passes of the satellite during the defined time window. Submit a TLE string that is close to the time window defined (maximum a couple of days old). The older the TLE, the less accurate the results that are returned.

Now, execute the command. It should send the message, and the server returns a[il] HTTP/1.1 202 Accepted [/il], if everything went well. If you get a[il] 401 [/il], something was wrong with your authentication. If you get a timeout, you either misspelled the server’s address, or our server is down. If you get a[il] 500 [/il], most probable your request contained some wrong format. In that case (and in all other cases), check out the response. A good response looks like this:

{
    "request_id":"2c4fabb8-dc30-4464-bc9d-01caf118e329",
    "stateMsg":{
        "text":"No messages available.",
        "type":"NONE"
    }
}

Most important is the request_id. Use this value to retrieve the result from your computation. In the state message, you will get some further information if the request was not accepted.

3. Receiving the result

You have now sent the first request, now it is time to collect the response. For this, note two things:

Your request needs a certain time for processing. For the pass prediction, it is generally less than a second, but give the server some time. If you asked for a response too soon, the server will return a[il] 202 [/il] instead of [il] 200 [/il], which means that the results are being processed now. The results you receive are incomplete. You can use[il] sleep 2 [/il] for the bash to wait for 2 seconds.
The responses are not saved for eternity on the server. Currently, the standard is 30 seconds. Thus, if you are doing this tutorial for the first time, remember to re-send the request once in a while, because your result might have been deleted already. If you ran the commands directly from the console, this is the point to start using a bash script.

The command to retrieve the results is:

request_id=`cat request_response.json | jq '.request_id' | sed -e 's/^"//' -e 's/"$//'`
wget --content-on-error --output-document=pass_prediction_result.json --header="access_token: ${ACCESS_TOKEN_VALUE}" http://okapi.ddns.net:34568/predict-passes/sgp4/summary/results/${request_id}

The first line is again a shortcut to read the request_id from the server response of the request and strip the quotes from the request_id. If you have no access to jq, you can also just copy the number from that file. Same is valid for the access token, which is assumed to be contained in the same variable as for the request sent before. You can directly execute this command. You should receive a[il] HTTP/1.1 200 OK [/il] from the server. This means, all went as it was supposed to be. Possible other responses are

[il] 202 [/il]: It indicates that the results are being processed now and the received content is not the complete yet.
[il] 404 [/il]: In this case either no pass was calculated because the satellite is not seen from the groundstation during the time window (this will be changed soon), or your request has not been processed yet.
[il] 422 [/il]: Unprocessible entity. Here, something was wrong with your request, which could not be detected by the API directly. Most probable, there is a defect in the TLE string. Check our the response, there should be more information available in the state message.

If everything went fine, look at your pass_prediction_result.json. It contains a summary of all passes of the object during the specified time interval. For a more readable version of the result, use [il] cat pass_prediction_results.json | jq .[/il] in your terminal.

Powershell

If you are using Windows as your operating system, you should have access to the powershell. Note that your admin has to grant you the right to execute powershell scripts before you can do that (look for the Set-ExecutionPolicy cmdlet)! Before getting started, one last recommendation: While it is possible to run the commands inline, we recommend you to paste them one-by-one in a shell script! This will facilitate all future requests and furthermore make the debugging much easier. Furthermore, some of the operations are time critical to a certain degree. When embedded in a script, you do not have to worry about that. If you prefer reading to writing yourself, the code that is to be created in this tutorial can also be found here.

1. Authentication

To be able to use OKAPI, you have to authenticate. We use services from Auth0 for that. Therefore, before being able to send any requests to our server, you have to get a token from Auth0. This token is received by sending a HTTP POST request to Auth0. As every HTTP request, it contains a header, and a body. When using wget, it is most easy to send the body as a file (note: One powershell, wget is an alias for the Invoke-WebRequest cmdlet). Depending on the programming language you will work with in the future, you can use build-in data types for that (for example structs in Matlab, or dicts and lists in Python). The body file to send an authentication request to Auth0 looks as follows:

{
    "grant_type":"password",
    "username": "<your_username_as_string_in>",
    "password": "<your_password_as_string_in>",
    "audience": "https://api.okapiorbits.space/picard",
    "client_id": "jrk0ZTrTuApxUstXcXdu9r71IX5IeKD3",
    "scope": <requested_scopes_as_strings_in_"_">
}

wget -Uri https://okapi-development.eu.auth0.com/oauth/token -Headers @{"content-type"="application/json"} -Method POST -Body $(get-content authentication_request.json -raw) -OutFile "token.json"

{
    "access_token": "<very_long_string_with_token>",
    "scope": "<string_with_your_scopes>",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Important in here are the scope and expires_in fields: In the first, all the endpoints you have access to are defined. When using the Demo account, you have full access to all available endpoints for a duration of 30 days. After that, the endpoints depend on your plan. The second field tells you how long the token is valid in seconds. Current standard is 86400 seconds ( = 1 day). After that, you would have to get the token again. If you are using OKAPI frequently, you could just create a recurring job (for example using cronjob), which refreshes your token automatically once per day.

2. Sending the first request

Now you have finished the authentication, so you are ready to send your first request. Using wget, the command to do that is the following:

$token = (Get-Content '.\token.json' | ConvertFrom-Json).access_token
wget -Uri http://okapi.ddns.net:34568/predict-passes/sgp4/requests -Headers @{"content-type"="application/json";"Accept"="application/json";"access_token"=$token} -Method POST -Body $(get-content pass_prediction_request.json -raw) -OutFile "request_response.json"
Start-Sleep -s 2

The first line is a “short-cut” to get the token from the token.json file. You basically read the value of the access token from that file and send it to the token variable.
The second line is the actual request. It is very similar to the command to retrieve the access token: Again, you define a body (given as a file, we come to that just after) and the header. This time, the header needs to now the content-type and the accept value. Furthermore, you include the access token, which is why we copied it into the variable (if you are unable to use jq, you have to copy the value of the access token into the request). This time, instead of using the GET method we use POST. Furthermore, the request is send directly to OKAPI, using the endpoint for pass-prediction requests. Also as before, the response from the server is written to an output file, which we call request_response.json. The Start-Sleep is included in the command to give the server a moment to process the request before you continue (which is important during the next step).

{
    "tle":"1 25544U 98067A   18218.76369510  .00001449  00000-0  29472-4 0  9993\n2 25544  51.6423 126.6422 0005481  33.3092  62.9075 15.53806849126382",
    "simple_ground_location":{
        "longitude":10.645,
        "latitude":52.3283,
        "altitude":0.048
    },
    "time_window":{
        "start":"2018-08-06T18:19:44.256628Z",
        "end":"2018-08-07T00:00:00.000Z"
    }
}

Note that the current version requires you to insert a TLE to describe the satellite’s orbit. Future releases will support a much larger variety of inputs formats. Furthermore note that you have to keep the format exactly as described above, including the leading blanks and newline statements. The location of the ground station is given in WGS-84 coordinates. Longitude and latitude are given in degree, the altitude in km. OKAPI will return all passes of the satellite during the defined time window. Note to submit a TLE string that is close to the time window defined (maximum a couple of days old). The older the TLE, the less accurate the results that are returned.

Now, execute the command. It should send the message and the server should return a[il] 202 [/il], which shows that the request has been accepted. Sadly, it does not really work in powershell to write the content of the response to a file and at the same time show the raw content (which includes the HTTP status) on the console. If you are interested to see it, simply send the wget command without the trailing[il] outfile [/il] option. Nevertheless, even though you won’t notice when something is correct, you will get notified in case of errors. If you get a[il] 401 [/il], something was wrong with your authentication. If you get a timeout, your either misspelled the server’s address, or our server is down. If you get a[il] 500 [/il], most probably your request contained some wrong format. In that case (and in all other cases), check out the response. A good response looks like:

{
    "request_id":"2c4fabb8-dc30-4464-bc9d-01caf118e329",
    "stateMsg":{
        "text":"No messages available.",
        "type":"NONE"
    }
}

Most important is the request_id. Use this value to retrieve the result from your computation. In the state message, you will get some further information if the request was not accepted.

3. Receiving the result

You have now sent the first request, now it is time to collect the response. For this, note two things:

Your request needs a certain time for processing. For the pass prediction, it is generally less than a second, but give the server some time. If you asked for a response too soon, the server will return a[il] 404 [/il], which means that no result was found. You can use[il] Start-Sleep 2 [/il] for powershell to wait for 2 seconds.
The responses are not saved for eternity on the server. Currently, the standard is 30 seconds. Thus, if you are doing this tutorial for the first time, remember to re-send the request once in a while, because your result might have been deleted already. If you ran the commands directly from the console, this is the point to start using a powershell script.

The command to retrieve the results is:

$request_id = (Get-Content '.\request_response.json' | ConvertFrom-Json).request_id
wget -Uri http://okapi.ddns.net:34568/predict-passes/sgp4/summary/results/${request_id} -Headers @{"access_token"=$token} -OutFile "pass_prediction_result.json"

The first line is again a shortcut to read the request_id from the server response of the request. The access token is still assumed to be contained in the same variable as before. Execute this command. You should now receive a[il] 200[/il] (which you will not see). This means, all went as it was supposed to be. Possible other responses are:

[il] 202 [/il]: It indicates that the results are being processed now and the received content is not the complete yet.
[il] 404 [/il]: In this case either no pass was calculated because the satellite is not seen from the groundstation during the time window (this will be changed soon), or your request has not been processed yet.
[il] 422 [/il]: Unprocessible entity. Here, something was wrong with your request, which could not be detected by the API directly. Most probable, there is a defect in the TLE string. Check our the response, there should be more information available in the state message.

If everything went fine, look at your pass_prediction_result.json. It contains a summary of all passes of the object during the specified time interval. For a more readable version of the result, use[il] Get-Content .\pass_prediction_result.json | ConvertFrom-Json | ConvertTo-Json [/il]. in your terminal.

Currently known shortcomings

The software is in a beta status. It comes with no warranty, guarantees etc., it is just a system to test the interface.
Currently, the data stays in the system for 30 seconds. This can, however, be adjusted without a problem.
A very high availability and long-time durability can’t be guaranteed at this point. However, the server should restart if something went wrong.
We plan to change the server address. Of course, we will notify you in advance, when this will be the case.
The request JSON must be formatted without any white space (spaces or line ends).
The predict-passes request can currently go 1 day ahead of the epoch of the state vector. We are working on removing this restriction.

Cookie	Duration	Description
_ga	400 days	This cookie is set by Google Analytics.
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.