Representational State Transfer (REST) is a fancy way of saying CRUD over HTTP. What this means is, when you use a REST API, you have a uniform means to create, read, and update data using simple HTTP URLs with a standard set of HTTP verbs. The most basic form of a REST API will accept one of the HTTP verbs at a URL and return some kind of data as a response.
Typically, a REST API GET request will always return some kind of data, such as JSON, XML, HTML, or plain text. A POST or PUT request to a RESTful API URL will accept data to create or update. The URL for a RESTful API is known as an endpoint, and when working with these endpoints, it is typically said that you are consuming them. The standard HTTP verbs used while interfacing with REST APIs include:
- GET: This retrieves data
- POST: This submits data for a new record
- PUT: This submits data to update an existing record
- PATCH: This submits a date to update only specific parts of an existing record
- DELETE: This deletes a specific record
Typically, RESTful API endpoints are defined in a way such that they mimic the data models and have semantic URLs that are somewhat representative of the data models. What this means is that to request a list of models, for example, you would access an API endpoint of /models. Likewise, to retrieve a specific model by its ID, you would include that in the endpoint URL via /models/:Id.
Some sample RESTful API endpoint URLs are as follows:
- GET http://myapi.com/v1/accounts: This returns a list of accounts
- GET http://myapi.com/v1/accounts/1: This returns a single account
by Id: 1 - POST http://myapi.com/v1/accounts: This creates a new account
(data submitted as a part of the request) - PUT http://myapi.com/v1/accounts/1: This updates an existing
account by Id: 1 (data submitted as part of the request) - GET http://myapi.com/v1/accounts/1/orders: This returns a list of orders for account Id: 1
- GET http://myapi.com/v1/accounts/1/orders/21345: This returns the details for a single order by Order Id: 21345 for account Id: 1
It's not a requirement that the URL endpoints match this pattern; it's just common convention.