Unimplemented API Methods

[grahhnt]

• All endpoints can return 401 if user is not logged in
• Endpoint successes should return modified or created document when applicable
• Protected endpoints can be used inside a web management interface for network staff

City Projects

(Some methods already exist)

POST /api/v1/city_project

Create a new City Project

Form:

ID is not included as it'll be generated by the API

• country_id (Integer) country ID, should be validated as a valid country before returning a response
• name (String) name of the city project
• description (String) description of the city project
• visible (Boolean) if city is enabled/visible

Returns:

200 JSON representation of the city project (GET /api/v1/city_project/:id). This is where you'd also get the ID of the added city project.

PUT /api/v1/city_project/:id

Update city project

Params:

• :id city project id

Form:

• name? String
• description? String
• visibility? Boolean

If value is missing, don't change that value If value is null, change value to null

Returns:

200 if successfully modified 404 this project does not exist 403 if user cannot modify this city project (wrong team) 400 if value is not the correct type or cannot be casted

DELETE /api/v1/city_project/:id

Delete city project

Params:

• :id city project id

Returns:

200 if successfully deleted 404 this project does not exist 403 if user cannot modify this city project (wrong team)

Builders

GET /api/v1/builders

Get all builders for authenticated build team

Query:

• ?show=all get all builders(?)

Returns:

200 with builders represented as JSON

GET /api/v1/builder/:uuid

Get specified builder

Params:

• :uuid builder's UUID (accepts either with dashes or without dashes)

Returns:

200 with builder represented as JSON 404 builder does not exist

POST /api/v1/builder

Create builder.

This should be protected and only be used by the network instead of individual build teams.

Form:

• uuid String
• name (String) Builder's current username (updated every connect to network)

Returns:

• 200 successful; return builder json
• 400 builder already exists

PUT /api/v1/builder/:uuid

Update a builder. Protected.

This API call could be used within a web management interface by network staff.

Params:

• :uuid builder's UUID (accepts either with dashes or without dashes)

Form:

• name (String) update builder's name
• score (Integer) update builder's total score (will automatically be updated by other API calls; eg scoring)
• completedPlots (Integer) update builder's plot completed count (will be automatically be updated by other API calls; eg scoring)
• firstSlot (Integer) plot id of slot one (automatically updated by other API calls)
• secondSlot (Integer) plot id of slot one (automatically updated by other API calls)
• thirdSlot (Integer) plot id of slot one (automatically updated by other API calls)

Returns:

200 successfully updated 400 incorrect form value type (eg not integer) 403 if requester is not network staff

POST /api/v1/builder/:uuid/plot

Add a plot to a player.

Params:

• :uuid builder's UUID (accepts either with dashes or without dashes)

Form:

• plot (Integer) plot id

Returns:

200 builder JSON & what slot the plot got added in

{
  "builder": {"builder": "json"},
  "added_to_slot": 1, // could be 0,1,2 - matching array indexes
}

400 builder already has 3 plots 404 builder doesn't exist (check uuid) 404 plot doesn't exist 403 plot doesn't belong to authenticated team

DELETE /api/v1/builder/:uuid/plot/:slot

Remove a plot assigned to a player

Params:

• :uuid builder's UUID (accepts either with dashes or without dashes)
• :slot slot array index (0,1,2)

Returns:

200 success 400 slot already empty 404 builder not found 403 plot doesn't belong to authenticated team

Countries

GET /api/v1/countries

Returns all countries

Returns

200 all countries as JSON

GET /api/v1/country/:id

Gets a specific country

Params

• :id country id

Returns:

200 country JSON 404 country not found

POST /api/v1/country

Protected.

Form:

• serverId (Integer) server id (foreign key of plotsystem_servers)
• name (String) server name
• headId? (Integer) head id from headdb (nullable)

Returns:

200 success 400 one or more of the values are of the wrong type 400 serverId doesn't match to a server registered

PUT /api/v1/country/:id

Update a country. Protected.

Params:

• :id country id

Form:

• serverId (Integer) server id (foreign key of plotsystem_servers)
• name (String) server name
• headId? (Integer) head id from headdb (nullable)

Returns:

200 success 400 one or more of the values are of the wrong type 400 serverId doesn't match to a server registered 404 country not found

DELETE /api/v1/country/:id

Delete a country. Protected.

Params:

• :id country id

Returns:

200 success 404 country doesn't exist

Difficulties

GET /api/v1/difficulties

Get all difficulties

Returns:

200 difficulties as JSON

POST /api/v1/difficulty

Create a difficulty. Protected.

Form:

• name (String) difficulty name
• multiplier (Double) score multiplier
• scoreRequirements (Integer) score requirement for using this difficulty

Returns:

200 success 400 Invalid value type

PUT /api/v1/difficulty/:id

Update a difficulty. Protected.

Params:

• :id difficulty id

Form:

• name (String) difficulty name
• multiplier (Double) score multiplier
• scoreRequirements (Integer) score requirement for using this difficulty

Returns:

200 success 400 invalid value type 404 difficulty not found

DELETE /api/v1/difficulty/:id

deletes a difficulty. protected.

Params:

• :id difficulty id

Returns

200 success 404 difficulty not found

FTP Configuration

(Some methods already exist)

GET /api/v1/ftps

Get FTP connections configured. Protected.

Returns

200 all FTP servers configured (contains usernames & passwords)

GET /api/v1/ftp/:id

Get FTP configuration

Params:

• :id ftp configuration id

Returns:

200 ftp configuration 404 ftp configuration doesn't exist

POST /api/v1/ftp

Create FTP configuration

Form:

• address (String) ftp server host
• port (Integer) ftp server port
• sftp (Boolean) if the server is SFTP
• username (String) ftp server username
• password (String) ftp server password
• schematicsPath (String) path on the ftp server to place schematics

Returns:

200 success 400 one or more of the values is of the wrong type 400 unable to connect and place test file in schematics path

PUT /api/v1/ftp/:id

Update FTP configuration

Params:

• :id ftp configuration id

Form:

• address (String) ftp server host
• port (Integer) ftp server port
• sftp (Boolean) if the server is SFTP
• username (String) ftp server username
• password (String) ftp server password
• schematicsPath (String) path on the ftp server to place schematics

Returns:

200 success 400 one or more of the values is of the wrong type 400 unable to connect and place test file in schematics path 404 ftp configuration doesn't exist

DELETE /api/v1/ftp/:id

Delete FTP configuration

Params:

• :id ftp configuration id

Returns

200 success 404 ftp configuration doesn't exist

Plots

(Some methods already implemented)

POST /api/v1/plot

Create a plot. (this should replace POST /api/v1/plot/add that's already existing)

Values not mentioned in the form should be null (or equivilent)

Form:

• city_project_id (Integer - plotsystem_city_projects) city project this plot is for
• difficulty_id (Integer - plotsystem_difficulties) difficulty setting this plot is at
• mc_coordinates (String) coordinates in server
• outline (String) bounding box of plot in mc coords
• create_player (String) uuid of player who created the plot

Returns:

200 success 400 one of the values is missing or wrong type 400 city project doesn't exist 400 difficulty doesn't exist 403 city project isn't owned by authenticated team

PUT /api/v1/plot/:id

Updates a plot.

Params:

• :id plot id

Form:

All values optional, if not included in request, don't update

• city_project_id? (Integer - plotsystem_city_projects) city project this plot is for
• difficulty_id? (Integer - plotsystem_difficulties) difficulty setting this plot is at
• mc_coordinates? (String) coordinates in server
• outline? (String) bounding box of plot in mc coords
• create_player? (String) uuid of player who created the plot
• status? (Enum - [unclaimed,unfinished,unreviewed,completed])
• owner_uuid? (UUID/String) uuid of plot owner
• review_id? (Integer - plotsystem_reviews) review
• member_uuids? (UUID[]/String[]`) array of member uuids (comma separated?)
• score? (Integer) score of plot
• last_activity? (DateTime) last activity on plot (if not specified, update with now)
• pasted? (Boolean) if pasted

Returns:

200 success 400 missing or wrong type for value 400 one of the foreign keys doesn't match to a valid row 404 plot doesn't exist

DELETE /api/v1/plot/:id

Deletes a plot

Params

• :id plot id

Returns

200 success 404 plot doesn't exist 403 you don't own this plot

PUT /api/v1/plot/:id/review

Create or update review.

Creates a review in plotsystem_reviews then updates plot with review id

Params:

• :id plot id

Form:

• reviewer_uuid (UUID/String) reviewer's uuid
• rating (String) Comma separated values for 0-5 for each category
• feedback (String?) feedback for the builder (can be empty)
• reviewDate? (DateTime?) optional review date (if omitted or empty; use now)
• sent (Boolean)

Returns:

200 updated review 201 created review 400 one or more of the values is of the wrong type 404 plot doesn't exist

Reviews

GET /api/v1/reviews

Get all reviews for authenticated team

Query

• ?show=all get all reviews (protected)

Returns

200 all reviews

GET /api/v1/review/:id

Get review

Params:

• :id review id

Returns:

200 review 404 review doesn't exist

POST /api/v1/review

Not here! It's in PUT /api/v1/plot/:id/review

PUT /api/v1/review/:id

Not here! It's in PUT /api/v1/plot/:id/review

DELETE /api/v1/review/:id

Delete review

Params:

• :id review id

Returns

200 success 404 review doesn't exist

Servers

GET /api/v1/servers

Get servers. Protected.

Returns

200 all servers

GET /api/v1/server/:id

Get server. Protected.

Params:

• :id server id

Returns:

200 server 404 server doesn't exist

POST /api/v1/server

Create server. Protected.

Form:

• ftpId (Integer - plotsystem_ftp_configurations) ftp connection id
• name (String) server name

Returns:

200 success 400 one or more of the values is of the wrong type 400 ftp doesn't exist

PUT /api/v1/server/:id

Update server. Protected.

Params:

• :id server id

Form:

If value is omitted, don't update

• ftpId (Integer - plotsystem_ftp_configurations) ftp connection id
• name (String) server name

Returns:

200 success 400 one or more of the values is of the wrong type 400 ftp doesn't exist 404 server doesn't exist

DELETE /api/v1/server/:id

Delete server. Protected.

Params:

• :id server id

Returns

200 success 404 server doesn't exist

[grahhnt]

Updated: @MineFact requested some endpoints be protected (country updating, difficulty updating, reviews GET, servers GET)

[grahhnt]

City Projects 27be8d2cc1b8b53a9e8d448e857460b910a33267