Greenfinch API

This is an HTTP API into the NeoFS file system.

Currently this has initial support for object management. Please also see the following links:

Roadmap

  • Container management (creation/deletion/list/sharing)
  • Larger objects
  • Search attributes
  • Shared library (.so files)

POST /object/{containerId}

Request

Headers

  • containerId
    (required): The ID of the container to upload the object to
  • publicKey
    (required): The public key of the container owner
  • X-r
    (required): The (bigInt) r - the integer retrieved from the signature
  • X-s
    (required): The (bigInt) s - the integer retrieved from the signature
  • Content-Type: multipart/form-data
    Currently only multipart/form-data is supported (max. size is 32MB)

NB. The payload should be multipart/form-data.

Response

Success

  • Response code: 200
  • Content: {objectId}

Bad Request

  • Response code: 400
  • Content: error message defining issue with request

Server error

  • Response code: 502
  • Content: Issue with the session (recreate the signature)
  • Content: Issue with the payload (the payload was not of the correct content-type)

GET /object/{containerId}

Request

Headers

  • containerId
    (required): The ID of the container to list the objects in
  • publicKey
    (required): The public key of the container owner
  • X-r
    (required): The (bigInt) r - the integer retrieved from the signature
  • X-s
    (required): The (bigInt) s - the integer retrieved from the signature

Response

Success

  • Response code: 200
  • Content: [{objectId}, {objectId}, {objectId}]

Bad Request

  • Response code: 400
  • Content: error message defining issue with request

Server error

  • Response code: 502
  • Content: Issue with the session (recreate the signature)

GET /object/{containerId}/{objectId}

Request

Headers

  • containerId
    (required): The ID of the container that contains the object
  • objectId
    (required): The ID of the object to retrieve
  • publicKey
    (required): The public key of the container owner
  • X-r
    (required): The (bigInt) r - the integer retrieved from the signature
  • X-s
    (required): The (bigInt) s - the integer retrieved from the signature
  • Content-Type: multipart/form-data
    Currently only multipart/form-data is supported

Response

Success

  • Response code: 200
  • Header: 
    NEOFS-META: {metadata}
  • Content: []byte

Bad Request

  • Response code: 400
  • Content: error message defining issue with request

Server error

  • Response code: 502
  • Content: Issue with the session (recreate the signature)

HEAD /object/{containerId}/{objectId}
GET /object/data/{containerId}/{objectId}
NB. Not all servers respect the HEAD method.

Request

Headers

  • containerId
    (required): The ID of the container that contains the object
  • objectId
    (required): The ID of the object to retrieve the metadata of
  • publicKey
    (required): The public key of the container owner
  • X-r
    (required): The (bigInt) r - the integer retrieved from the signature
  • X-s
    (required): The (bigInt) s - the integer retrieved from the signature

Response

Success

  • Response code: 200
  • Header: 
    NEOFS-META: {metadata}

Bad Request

  • Response code: 400
  • Content: error message defining issue with request

Server error

  • Response code: 502
  • Content: Issue with the session (recreate the signature)

DELETE /object/{containerId}/{objectId}

Request

Headers

  • containerId
    (required): The ID of the container that contains the object
  • objectId
    (required): The ID of the object to delete
  • publicKey
    (required): The public key of the container owner
  • X-r
    (required): The (bigInt) r - the integer retrieved from the signature
  • X-s
    (required): The (bigInt) s - the integer retrieved from the signature

Response

Success

  • Response code: 204

Bad Request

  • Response code: 400
  • Content: error message defining issue with request

Server error

  • Response code: 502
  • Content: Issue with the session (recreate the signature)

Greenfinch API Sandbox

Try the API here.

In short, this API allows a container owner to interact with their container and objects over HTTP without sharing their private key.

Watch a demo video of using the Sandbox here

You need to have the following:

  • A containerID and the public key of the container owner
  • Send these to the API to receive a bearer token
  • Use this token and your private key to sign the bearer token

Now you can upload an object...

  • Or you can retrieve details of an object
  • Or you can list all objects
  • Or you can delete an object
1. Request new bearer token

Before any request you will need a bearer token. You can specify how long a token should last.

Public key
Container ID 

                        
                    

                

            

            

                

                    

                        
2. Sign the bearer token

                        
Now, with your private key, you need to sign the bearer token. This will respond with two integers, r and s.

                        

                            Private key
                            
                        

                        
                        
                            

                                
                        
                    

                

            

        

        

            

                

                    

                        
3. Use the signature to upload

                        
Use the signature to upload some data to the contain.


                        

                            

                                
                              
                                
                                
                            

                            
                        


                        
                        
                        
                        
                            

                        
                    

                

            

        

        

            

                

                    

                        
4. Use the signature to retrieve

                        
The signature can now be used to make a request.

                        NB. You do need to have the file type above selected first.

                        

                             
                            

                                
                                
                                
                            

                            
                        

                        

                            Object ID
                            
                        

                        
                        
                        
                            

                            

                            

                        
                    

                

            

        

    

    

        

            

                

                    
                    
How can we improve Greenfinch? Find us on Discord.