Mar 31, 2018

Often times I will want to make an extremely simple web app, such as a TV Tracking App where I can enter in a few show names and have those names persisted. Most modern web applications have both a frontend and a backend API, typically written in either Java, Python, C#, TypeScript/JavaScript, or Golang. That backend will typically have a database such as PostgreSQL or MongoDB for persistence, increasing complexity and typically requiring at minimum a VPS to launch the application (i.e a private server where you can perform system administration directly).

A Simpler API

This post serves as a very simple example of how you can create a Flat File CMS API using just one PHP file. What is great about this strategy is if you just want to make some sort of proof of concept or a really simple web application for yourself that really doesn’t need the complexities of a backend API. What this does is essentially gives you the power to write, update, delete, and read from a JSON file with ease via simple POST or GET requests with a secret private key. Note that there is no user management in this and all data is readable if someone knows where the JSON file is, so this is not a strategy for storing sensitive information.

The Full Code

You can find the full repo that I referencing on GitHub.

Example

The example found in store.php enables adding data to a file named shows.json. I made this simple script because I wanted to set up a TV tracking app but not actually build any sort of backend API since that seemed like a bit of an overkill. You can definitely extend this to allow editing any file via a GET parameter but that could potentially open you up to a hacker creating whatever files they want on your website, given that they could only write JSON to them.

Note that there is literally no validation in this API, so it assumes that you are the one creating whatever interacts with the API and that you are extremely careful to not send malformed data. This would not work very well on a large team, but you could always use this as a base and expand upon it to add validation and more complex authentication.

Using the API

Key based authentication

Line 6 of store.php has the following line:

if($_GET['key'] == 'random_key') {

random_key should be updated to an actual random alphanumeric key that you want to use to authenticate against the PHP CRUD API. Note that anyone with the key could add, edit, and delete data so make sure it is both long and sufficiently random.

Data Structure

This API assumes that you are creating an array of data, but each element in the array does not need to have the same structure. You can also have a single element array if you simply want to have a single entry. You may use any keys you want and assign any values, but the key id is reserved and indicates the index of the element in the array. You may assign a different value to id but it will be ignored and instead changed to be the index of the element.

All Endpoints

All endpoints will return the full JSON data from shows.json after the modifications are made as desired.

Add Endpoint

This endpoint appends an element to the array.

URL:

store.php?key=random_key&method=add

POST data example:

{"name":"curb enthusiasm"}

This would add the above element and also add the id key to the element and store it in shows.json.

More complex POST data:

{
  "name:"curb enthusiasm",
  "date":"2018-03-31",
  "airing": false
  "related-shows": [
    {"name":"seinfeld"}
  ]
}

You can literally put as much or little data as you want.

Update Endpoint

This endpoint simply clobbers the data for the endpoint you provide and replaces it with the data you provide. If you do not include all keys, then the left out keys will be deleted.

URL:

store.php?key=random_key&method=update

POST data example:

{
  "id":0
  "name":"modern family"
}

This would update the first element in the array to have the only the data “name”:”modern family” (and the implicit id).

Delete Endpoint

Deletes the element with the id specified. All other keys will be ignored. The id indexes will be reset for all items to be in order.

URL:

store.php?key=random_key&method=delete

POST data example:

{
  "id":0
}

This would cause the element with “id”:1 to be reset to “id”:0 since the element with “id”:0 was deleted.

Read Endpoint

Just reads out the raw JSON data from the shows.json file.

URL:

store.php?key=random_key&method=read

Any POST data will be ignored, but you can call this endpoint either via POST or GET, doesn’t really matter in this case.