What is GET?
A GET request is the most basic API HTTP request method, and a great place to start in your understanding of APIs and HTTP protocol. The GET method retrieves information from a web server via an API call and returns it to the client that initiated the request. It's a basic but powerful process. You can GET live information from any API endpoint you have access to via authentication, and act on it immediately. This means weather reports, stock numbers, payments- anything can be flowing into your software via HTTP GET requests. Pretty cool!
GET example
We will use IP Geolocation to GET a resource from their API.
Our GET request will retrieve information based on our IP address. We are telling the API with the request header we want all of the content, and it is returned as a JSON file, which is a lightweight text file popular in REST APIs.
In your terminal, enter curl 'https://ipgeolocation.abstractapi.com/v1/?api_key={YOUR API KEY}'. You should get output similar to below:
json StatusCode : 200 StatusDescription : OK Content : {"ip_address":"174.49.204.134","city":"York","city_geoname_id":4562407,"region":"Pennsylvania","region_iso_code":"PA","region_geoname_id":6254927,"postal_code":"17402","country":"United States","count...
See the status code of `200`? You have completed your first GET request!
GET example: Query parameters
What if we don't want ALL the information from this request? You can choose to only receive a few fields from the JSON response using query parameters. Your request will look like this:
```curl `https://ipgeolocation.abstractapi.com/v1/?api_key={YOUR API KEY}&ip_address=166.171.248.255&fields=country,city````
If you did it correctly, it should return:
`http{ "country": "United States", "city": "Modesto"}`
More GET examples
- Retrieve a website: `curl https://www.abstractapi.com/`
- Retrieve the same website, but store the output to your local machine `curl -o example.html https://www.abstractapi.com/` (Extra credit: Store the output as a JSON file: `curl -o extracredit.json http://https://www.abstractapi.com/index.html`)
- Retrieve a website with verbose output, to see what cURL is doing behind the scenes `curl -v https://www.abstractapi.com/`
- In the last example, take a close look at cURL's verbose output. We see a GET request to `https://www.abstractapi.com/`, a received 1256-byte response, and the status code `200`, which indicates our request has succeeded! If you run this request as `curl -v www.examplefail.com`, you receive a failed GET message.
What's in a GET request?
- A Request-line: the `curl 'https://ipgeolocation.abstractapi.com/v1/?api_key={YOUR API KEY}'`.
- The HTTP method and the URI (Universal Resource Identifier) tell the API what they want to do, and where the specified resource is located or should go.
- Zero or more HTTP header fields. The request-header fields allow the client to pass additional information about the request, and about the client itself, to the server.
- An empty line indicating the end of the header fields.
- A message-body.
Conclusion
A GET operation is one of the cornerstones of REST API operations, which standardizes the HTTP communication between web services. The URL can itself refer to a web page, an image or a file. This is what makes GET so powerful- via REST APIs, a client can request and receive information from any API it has a key for. Continue learning more HTTP requests with the post request and the put request.
