API
APIs, EndPoints and REST
An API (Application Programming Interface) at a high level is a way to allow different applications to communicate. In the world of web applications this usually takes the form of Endpoints. An Endpoint is a specific URL, that in a well defined API, is set up to receive a specific HTTP call and response accordingly.
REST (Representational State Transfer) is an architecture style for designing networked applications. With web applications RESTful architectures are built around the HTTP Request Methods, often described as the HTTP Verbs, making calls against Endpoints.
Each HTTP verb is associated with a type of database interaction for example:
GET- Retrieve resource only. Most common type of request when browsing.
POST- Request that the server accept data. Typically used to send data from a form and for file uploads. Response not cacheable.
PUT- Used to update existing resource.
DELETE- Used to delete a resource.
PATCH- Used to partially update a resource.
OPTIONS- Call allows client to check what options/requirements a resource has.
HEAD- Similiar to GET but the server should only respond with the header no body.
RESTful calls can be made against your web application's Endpoints by other web applications using cURL technologies to create server to server calls. More commonly client side Javascript is used to make XHR/AJAX calls to an Endpont via the likes of fetch(). The client side Javascript could be contained within your own web application logic (in the wwwwroot folder) or in the case of open APIs by client side Javascript on third party webservers.
The returns from an Endpoint can vary in terms of content type. Most modern web application APIs will return JSON (Javascript Object Notation).
Buildng API
With Visual Studio and ASP.NET, APIs can by built either by:
- creating an API Only Projects;
- integrated API Endpoints into existing Projects;
Both techniques can make use of a scaffolding that can be based on Entity Framework. The scaffolding feature creates API Endpoints to match an Entity Framework model. We'll consider each of these techniques and look at ways of the various tools for testing Endpoints