Documentation

Quick Start Guide

200 OK provides you with a RESTful, CORS-enabled backend that only lives for 7 days after it has been created. It can be used for prototyping ideas or learning projects where you require a drop-in, ready-to-use backend without any configuration.

If you are familiar with REST APIs, you already know how to use 200 OK.

Your API backend follows the resource-based REST design approach and assumes that each request to a resource is made with purpose. If you want to store data for a user resource, you simply send a POST request to https://<your-API-name>.200ok.app/users, include a Content-Type: application/json header and send some valid JSON in your request body.

Your API automatically assigns an incrementing id field to that data and makes it available both as part of the resource collection (/users) and an individual collection item (/users/<id>).

You can issue requests for all of the basic CRUD operations:

Method	Target path	Response Status Code and Body on success
GET	a resource collection or individual item	200, requested data in body
POST	a resource collection	201, request body data plus added id field in response body
PUT	an individual resource item	204, no body
DELETE	a resource collection or individual item	204, no body

Resources can be nested up to four levels deep (e.g. /topics/1/posts/2/comments/3/likes), and each subresource is specific to an item of the parent resource (meaning that e.g. /posts/1/comments/1 and /posts/2/comments/1 refer to two different comments).

Upon creation, you receive an API key (a 24 digit alphanumerical string). By logging in via GitHub’s OAuth system, you can connect that API to your account and gain access to three additional features that might help in tailoring your backend to your needs:

1. A live inspector of your requests/responses (details)
2. A custom endpoint creator to specify JSON responses for certain API endpoints (details)
3. A way to set your API to private mode, requiring the correct authorization token to make requests to it (details)

For any further clarification, you can refer to the detailed documentation below.

Use cases

200 OK is intended as a learning and prototyping tool. If you are learning frontend web development, you might appreciate having a no-configuration API backend that you can use to test your client-side code.

Alternatively, if you are writing frontend code that will rely on a backend API later, but that API does not exist yet, you can mock the API for your frontend calls with 200 OK’s basic REST interface and the custom endpoint configurator.

You might also find yourself a participant in a hackathon, and you need a fire-and-forget-type of backend without any long-lived persistence. 200 OK is a good fit for that use case as well.

Core Principles of 200 OK

200 OK is an ephemeral, RESTful API service:

• Ephemeral means that each API will have a short life span: after seven days it will automatically be deleted, together with all its associated data.
• RESTful means that the API follows the common REST (Representational State Transfer) design principles.

They key concept is that of resources: A 200 OK API can be used to store, retrieve, update and delete information in the form of resources. Resources are represented as a collection of items (each one consisting of JSON-format data), with each item having a unique resource identifier.

The whole collection of resources as well as single items of a collection can be accessed with the commonly used HTTP request methods: GET for retrieval, POST for creation, PUT for updating and DELETE for deletion. See the section on RESTful requests for more on how to properly structure your requests.

Every 200 OK API is CORS-enabled and publicly accessible by default, so requests can come from any source, be it an application, client-side JavaScript code or the command line.

In order to create an API with 200 OK, you do not need to register or signup. It’s totally free and you can get your own API in a matter of seconds by clicking the big, shiny button labeled Create your API on the frontpage. If you have no need for any of the helpful tools that 200 OK provides, you only need to grab your API URL (in the form of https://<your-API-name>.200ok.app/ and you’re ready to go.

However, there are a few useful helper tools that you can access by logging in with your GitHub account and connecting your API. For that, you will need to enter your API name and the API key that you receive during the API creation step. Registering also comes with the possiblity of making your API private, restricting access by ways of requiring an authorization token to be sent with each request.

See the Tools section for more information.

RESTful requests

Resources and resource identifiers

The basic building block of a 200 OK API is the resource. Resources are the nouns that you can use to describe collections of information, be it users, documents or comments.

A simple resource can be accessed under the URI /<resource-name>. So a resource of users would have a fully qualified URL of https://<your-API-name>.200ok.app/users. This would represent a resource collection, comprising a varying number of individual users.

Note: For the purposes of readability, the documentation will use the shorter URI format for identifying resources and resource items, e.g. /users/5/images. To issue any valid request, you will of course have to provide your tool with the fully qualified URL to your API resource in the form of https://<your-API-name>.200ok.app/users/5/images.

Each item of a resource collection automatically receives an identifier in the form of an incrementing integer value (1, 2 etc.). The identifier is added automatically to each item when it is stored. That identifier can be used in the form of the URI /<resource-name>/<resource-identifier> to access an individual resource item.

/users/23 would therefore represent an item in the users resource collection with the identifier 23.

Resources can also be nested. Those nested resources belong to a specific resource item in the form of /<resource-name>/<resource-identifier>/<nested-resource-name>.

Going with the example above, each user could have an associated image resource. /users/42/images would then represent the images resource collection for the user with the identifier 42. Items from nested resource collections can otherwise be accessed the same way as any top-level resource.

In total, you can nest resources up to 4 levels deep (e.g. /users/1/galleries/2/images/3/comments/4).

Using HTTP requests

A 200 OK API assumes that each resource for which a request is received should exist. For that reason it is not necessary to explicitly create or delete a resource collection. Instead, any of the following operations will work on any resource, whether it has been explicitly accessed before or not.

There are four kinds of actions available on a resource collection or individual items, represented by an HTTP method:

• Retrieve collections or items (GET)
• Create collection items (POST)
• Update collection items (PUT)
• Delete collections or items (DELETE)

The data format for a 200 OK API is JSON (JavaScript Object Notation), so each resource item is represented by a valid JSON object, while resource collections will consist of an array of JSON objects.

Any data that you send to the API (e.g. in a PUT or POST request) needs to be valid JSON as well. In order for such a request body to be properly parsed by your API, you need to include a Content-Type header with the value application/json. Depending on the environment from which you make the request, this header might get automatically set.

A complete, valid HTTP POST request to a users resource might look as follows:

POST /users HTTP/1.1 
Host: <your-API-name>.200ok.app
User-Agent: exampleRequest-to-200ok
Content-Type: application/json
Accept: */*
Content-Length: 78
          
{
  "name": "Tom Bombadil",
  "altName": "Iarwain Ben-adar",
  "isEldest": true
}

Retrieval

A resource can either be retrieved as a whole (comprising all of its items) or by specifically requesting a certain resource item. This is done by making a GET request, which is the default request type for most browsers or HTTP utilities (like the curl command line tool or the in-browser fetch() method).

A GET request to /users would return the whole users resource collection as an array of JSON objects, while a GET request to /users/1337 would only return a JSON object for the item from users with the id field of 1337.

As was mentioned before, there is no need to explicitly create a resource collection itself. If, for example, you want to manage a resource for images, you can issue a GET request to https://<your-API-name>.200ok.app/images and receive an empty array as a response without having to create that collection first.

A successful response to a GET request will contain the requested data as well as a 200 OK status code.

Creation

To create a new resource item, a POST request needs to be issued to the collection itself. Keep in mind that there is no need to create the resource collection itself: If you want to send data for the first item in a comments resource collection, you can do so by directly sending JSON data to /comments.

In that case, the request body must contain valid JSON data which will be stored as is, with one notable exception: 200 OK automatically issues an id field for any newly created item. This operation will overwrite any id field values that you provide. This acts as a guarantee for consistent data and will prevent any accidental duplication of ids that might render parts of your resource collection inaccessible for GET requests.

The response to a POST request will contain the newly created item (comprising the data you sent as well as the newly created id field). This response will carry a 201 Created status code.

If, for example, you send the following JSON request body to /users:

{
  "name": "Glorfindel",
  "PlaceOfBirth": "Valinor",
  "isEldest": false
}

The response to that request will contain the following JSON body:

{
  "id": 1,
  "name": "Glorfindel",
  "placeOfBirth": "Valinor",
  "isEldest": false
}

The value of id is an incrementing integer number that allows you easy access to any resource collection item without having to remember or store more complicated labelling schemes.

Updating

In order to change the data represented by a resource item, a PUT request can be made to that resource item together with a JSON request body. Those requests are always considered as merge operations, meaning that whatever data you send with the request body gets merged with the already existing data: New fields are added and existing fields overwritten. Consequently, data will never be deleted by a PUT request.

If, for example, you want to update the dataset created above (because you don’t subscribe to the controversial theory that Glorfindel of Gondolin and Glorfindel of Rivendell are the same person), you would send a PUT request to /users/5. If it contains the following request body:

{
  "placeOfBirth": null
}

The resource item would look like this afterwards:

{
  "id": 1,
  "name": "Glorfindel",
  "placeOfBirth": null,
  "isEldest": false
}

A PUT operation will return a 204 No Content response status code to indicate a successful update.

Deletion

Deleting resource collections or items is a straightforward operation. By sending a DELETE request to either a resource colection or a resource item, it will be removed and you will receive a 204 No Content response upon successful completion.

Sending a DELETE request to /users/1 would thus delete the resource item with the id of 1 from the users collection.

Sending the DELETE request to /users instead, will delete all items in the users collection as well as all nested resource collections and their items.

So when deleting /users, if there was a collection /users/1/comments, it will be deleted as well. Be aware of the consequences of deleting whole collections!

Tools

Prerequisites

While the automatic RESTful operation mode might be sufficient for a big set of users, the need for more fine-grained control over your API might arise. Thus 200 OK allows you to go a step further and enable better debugging and configuration of your API backend.

Since those features require some form of user identification to prevent abuse, you will need to create an account. This can be done by logging in via a GitHub account. GitHub’s OAuth system will submit only a handful of profile information to 200 OK that is necessary to uniquely identify you, and 200 OK will store only a small subset of that information:

• your GitHub profile name
• your GitHub user id
• a link to your GitHub avatar image

Connecting and Managing your APIs

Once you have logged into 200 OK via GitHub, you have access to the Dashboard in which you can manage all your APIs.

If you have created your API before registering an account, you can retroactively claim it by using the Connect another API button in the Dashboard. For this you will need to enter both the name of your API (like noisy-darwin) and the 24-digit API key that you received upon the API’s creation.

If you do not remember the latter and did not save it somewhere, you are unfortunately not able to connect your existing API. However, since API creation is free, you can always just spawn a new one.

After entering both API name and API key, clicking Connect will tie the API to your account and subsequently display it under Your APIs in the Dashboard.

You can also directly create an API when you’re logged in by clicking Create a new API in the Dashboard or by clicking the button on the starting page and it will automatically be connected to your account without requiring the API key to do so.

You can have a maximum number of seven APIs connected to your account. If you have reached the maximum amount, you can delete your existing connected APIs from the dashboard, or you can simply wait until one of your APIs expires. This happens seven days after its creation, at which point it will automatically be removed from your account and all associated data will be deleted.

In the Dashboard, you can select a specific API by clicking on it in the Your APIs list. In the right panel you will now see details about that API: The creation date, how much time is left before the API expires and whether it is in public or private mode.

Below that, you will find several option buttons. You can enable or disable the API Authorization feature which puts your selected API in either private or public mode. By using the Inspect Requests/Responses tool, you can see a real-time overview of requests you make to an API as well as their accompanying responses. The Customize Endpoint Behavior feature allows you to define your own JSON responses for certain endpoints. Lastly, at the bottom of the API detail window, you find the link for the manual deletion of an API if you either don't need it anymore or want to start fresh with a new one.

Be aware, though, that you will lose all data stored via the API if you delete and there is no way to reverse that decision!

API Authorization

With API authorization enabled, you will need to send an Authorization header field with all your API requests. Once you click the Enable API Authorization button, you will receive a bearer token that will authorize your requests. The full header required for successful authorization would look like this:

Authorization: Bearer <your-token>

You will receive a response with a 401 Unauthorized status code and a descriptive error message if your requests lack the appropriate header or omit any necessary information.

To disable authorization, click the Disable API Authorization button after selecting the respective API from the dashboard list.

Request And Response Inspector

When first starting the inspection tool, there will not be much to look at. But every request that you issue to your API while the window is open will be displayed in real time on the page.

You can easily try this out by executing the suggested shell command, which will use the curl tool (available in both Linux and MacOS command lines by default) to make a simple GET request.

After making your first request, the page will immediately display a two-panel view, with all requests displayed in a list on the left side and the request and response details displayed on the right side. The request list will contain a short identifier in the form of <HTTP method> <requested path> to allow for a quick distinction between multiple requests.

When selecting a request by clicking on it, you can inspect both the request itself as well as the response received from your API in a tabbed view on the right side.

Being able to inspect requests and responses can provide you with valuable insight when you try to debug a non-working application or piece of code. Tools might hide their request implementation from you, e.g. setting headers that do not comply with how 200 OK works.

Customizing Endpoint Behavior

While the RESTful principles provide a lot of flexibility, your specific requirements might call for API behavior that does not translate well to the default resource-based approach. A good example would be a web frontend that at some point will have an API backend that allows for user login/logout at those respective endpoints: /login and /logout. Those are not resources (there should be no collection login with items like /login/1), so the standard behavior of the API will not match the intended use.

The Endpoint Customization tool allows you to overwrite this standard behavior of specific routes with your own responses. Thus, you can mock responses just like you expect them to be returned by a backend API.

Initially, your API will not have any custom endpoints, so you will see an empty selection list on the left side. Upon clicking New Custom Route, you will see a customization form on the right side which gives you full control over route behavior.

The endpoint path field defines the URI of your custom endpoint and you can immediately see the full URL under which that endpoint will be available later. For the login example above, we would therefore enter /login into that field.

There are four checkboxes below that toggle which of the four HTTP methods that endpoint should respond to: GET, POST, PUT and DELETE. You can select any combination of those four. So if our login example would call only for a POST request to login, all other checkboxes besides Allow POST requests could be disabled, making it the only valid operation for that endpoint.

If you enable a HTTP method, you can define a JSON response with which your API is going to respond. Please note that you are required to enter valid JSON data. If your input is malformed or contains characters or data types not supported by JSON, you will receive a warning message and will be unable to save your custom endpoint.

Once you are satisfied with your custom endpoint and have passed validation for your JSON response data, you can click Save Changes and will now be able to make requests to that endpoint and receive the custom responses.

There is currently no limit to the amount of custom endpoints you can create, so feel free to customize your API to your own liking.