Review of Fission API

1

Status codes

Goals

The goal of this document is to outline some proposed improvements to our API so that we can have a team discussion around the changes.

All proposed changes vary on when we should implement them.

Problems Identified

Status codes are lacking

A 500 on unauthorized is the most notable. This was why this investigation started. Essentially we have many cases where we could return a more informative status code.

Response Body’s are brittle

We often return data unwrapped. [1,2,3] instead of wrapped { list: [1,2,3] }. While valid this can cause breaking changes if we want to add additional fields in the future. Also the nature of wrapping responses in an object allows us to communicate meaning easier through field names.

Duplicate and or unused endpoints

In a few instances we had two endpoints doing the same thing: GET /ipf/{cid} and GET /ipfs?cid={cid}.

Misnamed endpoint

Currently PUT /ipfs/{cid} means pin this to your service. However POST /ipfs means create this file on ipfs and GET /ipfs/{cid} means give me the data for this cid from ipfs. I don’t think these necessarily line up. POST /ipfs/{cid}/pin would be a better endpoint for that functionality.

Proposed Endpoints, Status Codes and Responses

General error codes

Unauthorized -> 401
Ipfs Error -> 502
IPFS timeout -> 504

GET /dns/

note: this is a newly proposed endpoint

Status Codes

  • 200 OK*
  • 401 Unauthorized

Response Body*

{
	cid: 'abc1233'
}

PUT /dns​/{cid}

Status Codes

  • 201 Created*
  • 401 Unauthorized

Response Body*

{
	domain: 'subdomain.com'
}

GET /ipfs/cids

Status Codes

  • 401 Unauthorized
  • 200 Ok

Response Body*

{
	cids: [...]
}

GET /ipfs/{cid}

Status Codes

  • 401 Unauthorized

Response Body

{
  content: "..."
}

PUT /ipfs/{cid}

Status Codes

  • 401 Unauthorized

Response Body

POST /ipfs/{cid}

Status Codes

  • 401 Unauthorized

Response Body

PUT /ipfs/{cid}

Note: renamed from PUT /ipfs/{cid}

Status Codes

  • 401 Unauthorized
  • 400 Bad Request
  • 201 created

Response Body

{
  cid: "asdasdasd"
}

DELETE /ipfs/{cid}

Status Codes

  • 401 Unauthorized
  • 200 OK

Response Body

{
  cid: "asdasdasd"
}

POST /ipfs

Query Params

  • name

Status Codes

  • 401 Unauthorized
  • 201 Created
  • 400 Bad Request

Response Body

{
	cid: "abc123"
  name: "whatever.pdf"
}

POST /ipfs/dag

Status Codes

  • 401 Unauthorized
  • 201 Created
  • 400 Bad Request

Response Body

{
  cid: "abc123"
}

GET /ipfs/peers

Status Codes

  • 200 OK

Response Body

{
  peers: [...]
}

POST /heroku/resources

Status Codes

  • 401 Unauthorized
  • 201 Created
  • 400 Bad Request

Response Body

{
  "config": {
    "INTERPLANETARY_FISSION_PASSWORD": "GW0SHByPmY0.y+lg)x7De.PNmJvh1",
    "INTERPLANETARY_FISSION_USERNAME": "c74bd95b8555275277d4",
    "INTERPLANETARY_FISSION_URL": "https://runfission.com"
  },
  "id": 4213,
  "message": "Provisioned successfully"
}

DELETE /heroku/resources/{addon_id}

Status Codes

  • 401 Unauthorized
  • 404 Not found
  • 204 No Body

Response Body

GET ping

Status Codes

  • 200 OK

Response Body

pong

POST /user

Status Codes

  • 201 created
  • 400 bad request
  • 409 conflict

Response Body

{
  username: "user1"
  domain: "user1.runfission.com"
}

GET /user/verify

Status Codes

  • 200 OK

Response Body

{
  active: true
}

PUT /user/reset_password

Status Codes

  • 204 No Body
  • 401 Unauthorized
  • 400 bad request

Response Body

Endpoints to Remove

POST /ipfs/{cid}

  • http upload doesn’t need the cid

GET /ipfs

  • what are we getting?

PUT /ipfs

  • what are we putting without a cid?

Questions

  1. Why do we have GET ipfs/?cid=123 and GET ipfs/123
  2. How does POST /ipfs/dag work again?

Implemented Ideas

1. Rename PUT /ipfs/{cid} to PUT /ipfs/{cid}/pin
2. Add GET /dns which will return the current cid of their subdomain

What should we do

I think we should do the following:

  1. Update the API to use the updated general status codes for authorization and ipfs failure ASAP
  2. Create a card to update the rest of the agreed upon status codes
  3. create a card to add the GET /dns endpoint
  4. create cards update the response body’s and rename to PUT /ipfs/{cid} to POST /ipfs/{cid}/pin
2

I think DELETE needs /pin too — so /IPFS/{cid}/pin

Although DELETE could mean “nuke this file from disk”.

3

Removed the request to change PUT /ipfs/{cid} to POST /ipfs/{cid}/pin after a discussion with brooke

4

So, having some forwards-compatibility by wrapping in hashmaps is nice (subtype equality), and not even that hard to enable, but I’m still really struggling to find a user case for it beyond “maybe at some point we’ll want to send metadata along with requests”. After some in-person discussion with @boris, let’s put the JSON stuff on the deep back burner until we actually have a need in front of us.

5

Specifically — I want to prioritize user facing features with engineering work. Let’s talk more about this on Friday!

6

Would returning GET /ipfs/{cid} as a wrapped object prevent it from being used directly in webpages?

7

Indeed it would. We have since discussed how the server supports multiple content types, so the user can specify what format they want via headers. We don’t want to break expectations for non-JSON use cases, expected RESTful behaviours, and so on.

1 Like