diff --git a/source/getting-started/beginners-guide-to-apis/index.html.md.erb b/source/getting-started/beginners-guide-to-apis/index.html.md.erb deleted file mode 100644 index 6060e4e..0000000 --- a/source/getting-started/beginners-guide-to-apis/index.html.md.erb +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: Beginner's guide to APIs -last_reviewed_on: 2024-09-16 -review_in: 12 months -weight: 1 ---- - -# Beginner's guide to APIs - -In this guide, you'll learn the fundamentals of what HTTP is, what an API is, and how you can use -HTTP to interact with web APIs. - -An understanding of these topics is recommended before proceeding further with the Explore -education statistics (EES) API documentation. Most of the documentation requires a basic knowledge -of these concepts to be productive. - -## What is HTTP? - -HTTP stands for Hypertext Transfer Protocol, and it is used to transfer data over the web. It's -the language that web servers and browsers most commonly use to communicate with each other. - -To communicate with a server using HTTP, a client (e.g. a web browser or mobile phone) must send an -HTTP request. This contains information about the thing you're looking for or the action you -want to perform. - -Once an HTTP request has been received by the server (e.g. a website or web API), it will respond -with an HTTP response. This will contain the requested information and may specify how it should -be consumed or displayed to the end user. - -## What are APIs? - -APIs (application programming interfaces) are a set of protocols and rules used to build software -applications. Crucially, they allow different software applications to communicate with each other -using a common language. - -Web APIs, like the EES API, are servers (i.e. a computer hosted on the internet) that use HTTP to -communicate. Clients can send requests to web APIs to get them to do things like: - -- fetch or modify data stored in a database -- download or upload asset files (e.g. images, videos, documents) -- communicate with other APIs - -<%= tag :img, - :src => "/images/web-api-diagram.png", - :alt => "Diagram illustrating HTTP request / response between a client and web API, which may then communicate with a database, file store or other APIs" %> - -Websites and mobile applications are often built using web APIs to provide the data and assets that -will be displayed to the end user. - -## How to send requests to web APIs - -The recommended way to send requests to a web API is to use either an HTTP or API client tool. -Some good tools for beginners are [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/). - -HTTP and API client tools allow you to directly manipulate HTTP requests and all their constituent -components. This flexibility is needed to construct the different kinds of requests needed to use a -web API. - -Most API client tools will also re-format responses to make them more human-readable. Web APIs -will typically output their responses in the most compact form possible as they are intended to be -machine-readable by default. - -Web browsers can also be used to make requests to web API endpoints, however, this comes with the -caveat that only simple GET requests (using just the URL) are possible. Additionally, web browsers -will not display HTTP responses in a human-readable way by default. - -## How do HTTP requests work? - -HTTP requests are used by a client to request something from a server. A request contains multiple -components that provide the server with the information needed to respond correctly. - -The main components of a request will be discussed in more detail below. - -### URL (Uniform Resource Locator) - -A URL describes the path to a **resource** on the web and typically begins with `http://` or `https://`. -When a URL is typed into a web browser, it will typically take you to that resource. - -Examples of resources include things like: - -- web pages on a website -- data from a web API -- files (images, audio, videos, etc) - -### HTTP Method - -The HTTP method describes the type of request being made. There are many HTTP methods, however, -you'll typically only need GET, POST, PUT, PATCH and DELETE. - -The method is normally used to get the server to do different things, however, the server interpret -these differently depending on the use-case. Many servers adhere to some common conventions for -how methods should be used and interpreted: - -| Method | Sends data? | Changes server state? | Conventional usage | -|--------|-------------|-----------------------|-----------------------------------------------| -| GET | No | No | Get a resource | -| POST | Yes | Yes | Send some data to create a resource | -| PUT | Yes | Yes | Send some data to create or update a resource | -| PATCH | Yes | Yes | Send some data to update a resource | -| DELETE | No | Yes | Delete a resource | - -### Query string - -A query string appears at the end of a URL (after a `?`) and provides additional criteria for the -server to respond to. The following example contains a query string: - -``` -https://example.com/foods?category=fruit&colour=yellow -``` - -In the above example: - -- the URL is `https://example.com/foods` -- the query string is `category=fruit&colour=yellow` - -The query string can be interpreted by the server as a set of parameters specifying that the -category should be 'fruit' and the colour should be 'yellow'. Given these parameters, the server -may respond with a list of foods matching these criteria. - -### Request headers - -These are additional pieces of information that are sent with the request. They can contain details -about the client, or provide additional constraints on how the server should respond. - -Headers consist of a header name and its value, separated by a `:`. Some examples include: - -- the web browser or client e.g. `User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...` -- the media type of the request body e.g. `Content-Type: application/json` -- the accepted media types for the response body e.g. `Accept: text/html` -- authentication credentials e.g. `Authorization: Bearer ...` - -### Request body - -In cases where a request needs to send data to the server, this can be embedded in the request's -body. On a web browser, this is typically used by form submissions to contain the user's input. - -The request body is typically used with POST, PUT or PATCH methods to describe the change that -should occur on the server. - -The data should be formatted and encoded in a way that the server can understand. There are -different ways to do this, however, the most common ways are to use URL encoding or JSON. - -The type of data in the body should be indicated by the `Content-Type` header (see [Request headers](#request-headers)). - -## How do HTTP responses work? - -HTTP responses are used to send data from a server back to a client. A response consists of the -following components: - -### Status code - -This is a three-digit code that indicates the status of the response. Each status code indicates -different things e.g. - -- `200 OK` — the request succeeded -- `404 Not Found` — the server could not find the requested resource -- `500 Internal Server Error` — an error occurred whilst the server was fulfilling the request - -The status code will also fall into one of five groups indicating the type of response: - -| Range | Description | Examples | -|-----------|------------------------|--------------------------------------------------------| -| 100 - 199 | Informational response | `100 Continue` | -| 200 - 299 | Successful response | `200 OK`, `201 Created` | -| 300 - 399 | Redirection response | `301 Moved Permanently`, `302 Found` | -| 400 - 499 | Client error response | `400 Bad Request`, `404 Not Found` | -| 500 - 599 | Server error response | `500 Internal Server Error`, `503 Service Unavailable` | - -### Response headers - -Similar to request headers, a response can also contain headers. These are additional pieces of -information, typically containing details about the server and additional context about the -response that may be useful to the client. - -Some examples of response headers include: - -- the size of the response e.g. `Content-Length: 4123` -- the media type of the response body e.g. `Content-Type: text/html` -- the encoding of the response body e.g. `Content-Encoding: gzip` -- the URL to redirect to e.g. `Location: https://another-website.com` - -### Response body - -A response will typically contain data to send back to the client in its body. The data can be -essentially anything, but common examples include: - -- the HTML of a web page -- the text of a CSV -- the binary contents of an image, video, etc -- the JSON data from a database - -The type of data in the body should be indicated by the `Content-Type` header (see [Response headers](#response-headers)). - -## What is JSON? - -JSON (JavaScript Object Notation) is a lightweight data format that is easily understood by humans. -It is also easy for machines to parse and generate and is often used as the data format to communicate -with web APIs (including the EES API). - -The following is an example of some JSON: - -```json -{ - "name": "John Smith", - "age": 35, - "isRenting": true, - "car": null, - "pets": ["cat", "dog"], - "address": { - "city": "London" - } -} -``` - -In the above example, there is a JSON object with multiple keys such as `name` and `age`. -Each key has an associated value and each value can be one of the following data types: - -- string e.g. `"John Smith"`, `"London"`, `"cat"` -- number e.g. `35` -- boolean e.g `true`, `false` -- array e.g. `["cat", "dog"]` -- object e.g. `{ "city": "London" }` -- null - -Arrays are lists of values that are normally used to describe multiple things that have an order. - -Objects are made up of multiple key / value pairs. They are typically used to group related values in -the data, for example, an object could represent an address by containing the address lines, city, -postcode, etc. - -Both arrays and objects are compositional data types and can contain any of the data types within -themselves. This means that deeply nested data structures like the following are possible: - -```json -{ - "a": { - "b": [ - { "c": "..." } - ] - } -} -``` - -## What does communication with a web API look like? - -Web APIs can be structured in many ways, but the most common is to expose multiple **endpoints** -for clients to access. - -An **endpoint** is the URL of a resource on the server and may look something like the following: - -- `https://example.com/api/foods` — endpoint for 'food' resources -- `https://example.com/api/foods/1` — endpoint for the 'food' resource with ID = 1 - -Clients can make requests to an endpoint using different HTTP methods (e.g. GET, POST, etc) to -interact with it in different ways. Using the earlier endpoint examples, you can express the -following operations: - -- `GET /api/foods` — list foods -- `POST /api/foods` — create a new food -- `GET /api/foods/1` — get the food with ID 1 -- `PUT /api/foods/1` — update the food with ID 1 -- `DELETE /api/foods/1` — delete the food with ID 1 - -The above example illustrates the typical data operations possible with web APIs. These operations -are often described as CRUD (create, read, update, delete) operations. The EES API applies similar -conventions for its endpoints. - -Depending on the endpoint and the HTTP method, the request may need some combination of a body, -headers and query parameters. - -### GET example - -An example of a GET request would simply look like this: - -``` -GET https://example.com/api/foods HTTP/1.1 -``` - -The server could respond with a list of foods in the response: - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -[ - { - "id": 1, - "name": "milk", - "category": "dairy" - }, - { - "id": 2, - "name": "orange", - "category": "fruit" - } -] -``` - -The response contains a `Content-Type` header to inform the client about the media type of the -response body. In this case, it is set to `application/json` meaning that the response body -contains JSON data. - -### POST example - -An example of a POST request would look like: - -``` -POST https://example.com/api/foods HTTP/1.1 -Content-Type: application/json - -{ - "name": "lemon", - "category": "fruit" -} -``` - -This would create a new food with a `name` of 'lemon' and `category` of 'fruit'. - -The request contains a `Content-Type` header to inform the server about the media type of the request -body. In this case, it is set to `application/json` meaning that the response body contains JSON data. - -The server could then respond with a successful response indicating the food was created: - -``` -HTTP/1.1 201 Created -Content-Type: application/json - -{ - "id": 3, - "name": "lemon", - "category": "fruit" -} -``` - -In this response, the status code is `201 Created` and the response body contains the created food. - -## Conclusion - -Web APIs provide the core building blocks for creating websites and other applications on the modern -web. Understanding HTTP provides foundational knowledge that will allow you to effectively work with -web APIs. - -The EES API is a web API and having knowledge of all the discussed topics will provide you most of -the tools to become productive with the documentation. - -Once you feel ready to proceed with the rest of the documentation, it is recommended that you read -the [Quick start guide](/getting-started/quick-start/index.html) to get familiar with how the -EES API works. - -### Further reading - -1. [Basics of HTTP - MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP) diff --git a/source/getting-started/index.html.md.erb b/source/getting-started/index.html.md.erb index 7060cb2..7a743d2 100644 --- a/source/getting-started/index.html.md.erb +++ b/source/getting-started/index.html.md.erb @@ -16,25 +16,13 @@ To get started with the EES API, you'll need either: if you are exploring the API - an HTTP client in the programming language of your choice if you are developing on top of the API -## Where to start +The documentation on this website will assume a level of familiarity with how HTTP, web APIs and +REST work. You should research these topics prior to using the EES API if you are not familiar with +them. -There are three suggested starting points that are recommended depending on your knowledge of HTTP, -APIs and the EES API. - -### Beginner level - -If you are not familiar with how HTTP and APIs work, it is recommended that you start with the -[Beginner's guide to APIs](beginners-guide-to-apis/index.html). This guide will provide knowledge of -foundational concepts that will make you more productive with the rest of the API documentation. - -Once you are more confident with these topics, the [Quick start guide](quick-start/index.html) is -a good next step. - -### Intermediate level - -If you are familiar with how HTTP and APIs work, but are new to the EES API, it is recommended -that you start with the [Quick start guide](quick-start/index.html). This will guide you through -essential parts of the API and the workflow to perform a basic data set query. +It is recommended that you start with the [Quick start guide](quick-start/index.html) if you are +new to the EES API. This will guide you through essential parts of the API and the workflow to +perform a basic data set query. The [Overview](/overview/index.html) section is a good next step for a more in-depth understanding of the high level parts of the EES API. @@ -42,21 +30,15 @@ of the high level parts of the EES API. To assist in specific tasks once you've started using the EES API, there are additional guides under the 'Getting started' of the navigation menu that you may find useful. -### Expert level - -If you are already familiar with the EES API, you will find all relevant reference documentation in -the [Overview](/overview/index.html), [Endpoints](/endpoints/index.html) and [Schemas](/schemas/index.html) -sections. - ## Documentation structure -The [Overview section](/overview/index.html) provides high level documentation about the EES API. This details -things such as message formats, error handling, versioning and the OpenAPI specification. +The [Overview section](/overview/index.html) provides high level documentation about the EES API. +This details things such as message formats, error handling, versioning and the OpenAPI specification. -The [Endpoints section](/endpoints/index.html) provides reference documentation about the endpoints available -in the API. This details the requests that can be made and their responses. Code samples are also -provided to illustrate how requests could be made. +The [Endpoints section](/endpoints/index.html) provides reference documentation about the endpoints +available in the API. This details the requests that can be made and their responses. Code samples are +also provided to illustrate how requests could be made. -The [Schemas section](/schemas/index.html) provides reference documentation about the structure of all the -requests and responses (i.e. their schemas) across the API. Each schema provides in-depth detail -about their properties, including their type and validation rules. +The [Schemas section](/schemas/index.html) provides reference documentation about the structure of +all the requests and responses (i.e. their schemas) across the API. Each schema provides in-depth +detail about their properties, including their type and validation rules.