An Introduction to REST
Background
When we talk about our API, we use terms like REST and RESTful. While "REST" stands for Representational State Transfer, it is an architectural style that's an alternative to web services like RPC and SOAP.
There are a lot of common approaches and best practices used across the engineering community that helps to define how RESTful APIs should work. But there is no official REST standard. For example, most RESTful APIs follow these six specific constraints or design rules.
RESTful HTTP Methods
These standard predefined HTTP methods behave like the well known CRUD scheme from database operations like Create, Read, Update, Delete. You can map those operations to the standard HTTP methods. For example, use a POST request to create a new resource, a GET request to read or retrieve a resource, a PATCH request to edit a resource, and a DELETE request to delete a resource.
In the getting started guide you can have an overview what HTTP methods we have implemented in our API.
RESTful Features of the Checkdomain API
Nouns
RESTful APIs are based on resources, and share a well-defined and uniform interface. URLs and URIs in the API don't contain verbs because verbs can't be resources as per definition. That's why we avoid them in the URI and limit verbs to the HTTP method part of your request.
We are also talking/writing a lot about "endpoints" in our documentation. Endpoints are Uniform
Resource Identifier or in short URI for individual resources.
For example, find a collection of articles by requesting the /articles endpoint, or
access individual articles at /articles/{article}.
HTTP methods and response codes
We are constantly improving our API and are working on an full implementation of our services into out API - but always under the standard of REST. We do our best to build a REST compliant web service.
Just a short important notice:
- GET requests are safe, and won't alter a resource.
- PATCH and DELETE methods are idempotent.
- POST isn't safe or idempotent.
If your firewall rules don't support HTTP methods like PATCH or DELETE, use the
X-HTTP-Method-Override
header. Just pass the method you want to use in the X-HTTP-Method-Override header within your request
and make your call using the POST method. The override won't work with any other method, so if you try and use the
override header with a GET, PATCH, PUT, or DELETE method, you'll receive an error.
Please note, that every response with a 204 No Content HTTP status code will not have a
response body. All successful DELETE requests will answer with "204 No Content".
Discoverable
We are including hypermedia links in the resource representations returned by each successive call for machine readable code as defined under the HATEOAS discovery technique. ("Hypermedia As The Engine Of Application State")
But we don't expect you to traverse the API to make calls, so you can make deep calls directly. HATEOAS just improves the lead-in for first-time developer with the checkdomain API.
Deviations from REST
Generic MIME types
You could but don't have to send an Accept: application/json header in your request and our
API will respond with JSON. However it is possible to retrieve an XML response by sending an Accept: application/xml
header. Please note, that currently the only fully supported format is JSON and you should not use XML unless
you really have to.
Please note that at the end of an URI no trailing slashes are allowed. For example you
may want to access a resource like this: https://api.checkdomain.de/v1/articles
As you can see we left out the trailing slash. Should you provide a trailing slash the API will return an error.
Now, as a "professional" in REST architecture and how we implemented it in our checkdomain API, be sure to check out the API Reference.