The API is built using Laravel and restful principals. Check the Laravel Documentation to find out how they are implemented.

When you get a response from the server on a route it will look like this:

{
   'id:1,                    // The unique database key (integer) all records have these even if they're not returned
   'slug:'bob_stevens',      // The unique slug we recommend using to access records stored in the database
   'first_name':'Bob',       // A normal variable in the database (snake case)
   'last_name':'Stevens',    // A normal variable in the database (snake case)
   '_name':"Bob Stevens",    // A generated read only value (starting with _ underscore) you can't set these directly
   'comments':{              // A related table
      'id':'1',  
      'text':'Woah',         // Comment text 
      '_rank':22             // A generated read only value (starting with _ underscore)
   },
   '_vote_dates':{            // A generated read only value. It might look like a relation and have to do with a relation but it's not. We are moving all responses to snake case but some are still camel case.
      '2018-2-1','2019-3-1'  
   }
  }
}

When you send a request you will have to make sure you submit valid variables. Check the /app/Http/Requests folder to see what variables the controller you're trying to access will accept. Generally if you have the right permissions you can send back to the API updates to regular fields (like first_name, last_name) but you will not be able to update related elements or _generated_variables on this api end point.

The Bouncer We have a tool called "the bouncer" which triggers a 400 response when you submit values the API can't do anything with (typos, poorly sanitized data etc). When developing it's a good idea to just keep it on in your .env file or your code will fail tests when it's run on our CI server.

In the command line you can see the available routes by running the line:

php artisan route:list

/api/resource/ INDEX (get) Will return an index of the resource, query filters will make sure the default view is what you can actually see

/api/resource/store STORE (post) Does the initial store of a resource, returns the resource on success or will have an error if validation or permission failed

/api/resource/X SHOW (get) Will fetch this resource, if you are logged in it will get all the data you have permission for on this resource (to populate the edit form/review as well)

/api/resource/X UPDATE (patch) Does the store of the resource, takes updates with even just one field each time.

/api/resource/X DESTROY (delete) Deletes the record, sometimes soft deletes or setting it to a neutral position

These are dependent on other resources to exist so the are set to work with

/api/resource/ INDEX (get) Will return an index of the resource

/api/parentresource/resource STORE (post) Does the initial store of a resource tied to the (required) parent resource, returns the resource on success or will have an error if validation or permission failed

/api/parentresource/resource INDEX (get) Will return an index of the resource related to the parent resource. So the comments of a motion, or the comments of a user.

/api/resource/X SHOW (get) Will fetch this resource, if you are logged in it will get all the data you have permission for on this resource (to populate the edit form/review)

/api/resource/X/ UPDATE (patch) Does the store of the resource, takes updates with even just one field each time.

/api/resource/X DESTROY (delete) Deletes the record, sometimes soft deletes but if you run it twice it will delete it as far as it is able to