markdown REST API教程

Posted 2021-05-05

### Intro to Rest 
* Provides an inteface between two systems (client and server)
* Requests resource to and from a web server
* The languages do not matter, you can make a request in Ruby and get a response from a Java server
  * However, the request and response are returned in the same format (HTTP) 
---
### Using cURL
* stands for `client URL`
* terminal based command to obtain a response from an API call
* In terminal, to check if you have curl: `curl -V`
* Sample cURL command:

```ruby
curl -X GET "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"

# returns
{"coord":{"lon":-121.96,"lat":37.35},
"weather":[{"id":800,"main":"Clear","description":"clear sky","icon":"01d"}],
"base":"stations","main":{"temp":37.04,"pressure":1018,"humidity":55,"temp_min":35.6,"temp_max":41},
"visibility":16093,"wind":{"speed":6.93,"deg":330},"clouds":{"all":1},"dt":1550848500,
"sys":{"type":1,"id":5845,"message":0.0042,"country":"US",
"sunrise":1550846858,"sunset":1550886920},"id":420006397,"name":"Santa Clara","cod":200}
```

* to see the response header from a curl call, add `-i` to the call: `curl http://example.com -i`

```
curl -X GET 
-H "Cache-Control: no-cache" 
-H "Postman-Token: 930d08d6-7b2a-6ea2-0725-27324755c684" "https://api.openweathermap.org/data/2.5/weather?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial"
```

* `-X GET`: used to specify what kind of request (get, post, put, delete, ...)
* `-H`: used to specify what kind of information should be passed in the **header**

#### Query Strings and Params
```
?zip=95050&appid=fd4698c940c6d1da602a70ac34f0b147&units=imperial
```

* `?`: resources passed after the `?` are query string parameters
* need the `&` to concatenate multiple params

#### Other cURL Commands
* `-d` includes data to be posted to the url
#### A lot of APIs require you to post requests containing JSON messages in the body. Request body parameters are often how you configure a service.
* [CRUD with cURL](https://idratherbewriting.com/learnapidoc/docapis_curl_with_petstore.html)
---
### Parameters for API Calls
* REST API's have **4** types of parameters
  * **Header Parameters**
    * Parameters included in the request header, usually related to authorization 
    * _authorization details in header parameters are documented in the authorization requirements section of the api_
  * **Path Parameters**
    * Parameters before the `?`, usually denoted for resource id `/notes/{note_id}` 
  * **Query String Parameters**
    * Parameters that will appear in the URL, after the ?
  * **Request Body Parameters**
    * Parameters submitted in the body of the request, usually in JSON
    * More often used with `POST` requests