%% date:: [[2023-07-13]] parent:: %% # [[REST]] REpresentational State Transfer (REST) is a type of [[API]] that focuses on adding a structure to web services. [^coredna] An API that employes REST is sometimes called a RESTful API. ## Advantages of REST REST APIs are simple because clients using a REST API "learn" how to structure a request by parsing the responses of previous requests. In this way, there doesn't need to be any previously-agreed resource structure on the part of the requesting client. [^google] ## REST architecture ![[When and Why to Use GraphQL#^restfularch]] [^graphql] ## Example of a REST API How do you know what format you can use to formulate your requests in? That’s where API documentation comes in. Let's have a look at an example. Poké API is a collection of data about Pokémon, and their site includes a link to the [Poké API documentation](https://pokeapi.co/docs/v2.html/[[pokemon]]): `GET <https://pokeapi.co/api/v2/pokemon/>{id or name}` This is how you should formulate a request in order to retrieve information from their database. In this example: - `GET` is the method (or ”verb”) that describes what kind of request you’re making - `https://pokeapi.co/api/v2` is the base URL of the API - `/pokemon`is the endpoint we’re using and describes where the data we want is kept - `{id or name}` is extra information we want to send along with our request There are a few ways to actually consume (use) this API. In this case, let’s say we want to do a search in the database for details on the pokemon Vaporeon. Using the format of the request above, we can use this request: `GET https://pokeapi.co/api/v2/pokemon/vaporeon` You can test a simple GET request like this by typing `https://pokeapi.co/api/v2/pokemon/vaporeon` in your browser’s URL bar and hitting enter. You’ll likely see a LOT more information about Vaporeon than you ever wanted to know. To see a formatted version of all this data, use Poké API’s simple interface and type in `/pokemon/vaporeon`:  This returns the same data, but formatted better. You can also make the same requests using [cURL](https://curl.haxx.se/docs/manpage.html) via the command line or [Postman](https://www.getpostman.com/) for a friendlier interface.  _Using Postman to get information about Vaporeon_ Because the request is in a format that the application server understands, the application server replies and responds with the resources for that page. So **the API defines a language and syntax that clients (such as web browsers) need to use in order to interact with an application**.‌ There are several types of APIs, including [[Simple Object Access Protocol|SOAP]], REST, [[JSON-RPC]], and [[XML-RPC]]. Each one has a different standardized format for communicating with the web application. RESTful APIs (REST stands for REpresentational State Transfer) are particularly popular because of their simplicity. The Poké API is a RESTful or REST API. [^coredna]: Mason, J. (2021). _What is GraphQL? (And is it really better than REST)_. Retrieved from https://www.coredna.com/blogs/what-is-graphql . [^graphql]: Lombard, J. (2018). _When and why to use GraphQL_. Design Patterns. Retrieved from https://medium.com/@JeffLombardJr/when-and-why-to-use-graphql-24f6bce4839d . [[When and Why to Use GraphQL|My highlights]]. [^google]: Nally, M. (2020). *gRPC vs REST: Understanding gRPC, OpenAPI and REST and when to use them in API design.* Retrieved on July 13th, 2023 from https://cloud.google.com/blog/products/api-management/understanding-grpc-openapi-and-rest-and-when-to-use-them