This article is a very short primer on API basics. If you've never used APIs before, the CItyFALCON one is straightforward and easy to learn on. This article should get you started and introduce you to the most common terminology. You'll need to separately learn how to implement calls through your programming language of choice (Python, C, VBA, etc.).
What is an API?
An Application Programming Interface, or API, is a standardized way for programs to request information and data from a remote server. These can be termed API Requests or API Calls. The Response is the information that comes back from the server.
For us, the CityFALCON server can send and store various pieces of information, and you can access that information for your local program through the API.
Types of Requests
There are three call types associated with CityFALCON:
- GET calls retrieve data, usually taking certain parameters to narrow down the response
- POST calls tend to send information to the remote server, which often makes a permanent change to an account
- DELETE calls also send information to the server to make permanent changes
Parts of a Request
There are multiple parts to each request:
- Call type - GET, POST, or DELETE
- Header - standard information for the server, almost always the same for CityFALCON
- Body - information the server must process
- URL String - the base URL, the endpoints, and the parameters sent to the server
- Endpoint - embedded in the URL string, this compartmentalizes the service for different purposes (assets, stories, and banlists for us)
- Base URL - this is also part of the URL string, and it contains information on where to find the API server on the internet
CityFALCON Specifics
The three endpoints are Stories, Assets, and Banlists.
The Base URLs are
- https://sandbox-api.cityfalcon.com/v0.2/ for very basic testing and learning
- https://api.cityfalcon.com/v0.2/ for more robust testing and live applications.
Building a Query String
For CityFALCON, all GET calls are URL-based. You don't need to add anything to the request body. Simply add all the parameter and authentication information in the URL string.
To formulate the URL string,
- start with the URL base
- append the endpoint
- start your parameters with a question mark (?)
- separate parameters with an ampersand (&)
For example, if you want to see stories on Microsoft and Apple, you can use their tickers as their identifiers. You need to set the identifier_type parameter to tickers and the identifiers parameter to MSFT and AAPL.
The partial URL String would be:
base + endpoint + ? + parameters
or, with actual text,
https://sandbox-api.cityfalcon.com/v0.2/stories?identifier_type=tickers&identifiers=msft,aapl
This won't work right away, because you are missing the authentication token, but this method is how you build an API URL String.
Composing the Request Body
GET calls can be completed entirely as URL Strings. POSTs and DELETEs will require a little more.
In fact, the URL String only requires authentication for POST and DELETE, but you will need to add the information to be posted or deleted in the request body. This will vary by language, but generally you will just need to add the domain or article to be banned to the API request body and send it as a POST or DELETE request.
Authentication
On both the test and live versions, you need to authenticate yourself. If you signed up for the API, you will have received an API key. This is your authentication key. Simply add it in the URL string as
?access_token=[key]
where [key] is the key provided to you. It is fine to send the key just as it is. The connection to the API server will be HTTPS, which means it is already encrypted. Your key will be sent through the secure, encrypted tunnel, so you don't have to worry about protecting it from prying eyes.