REST API

REST API

This low-level API is the common ground between all REST services. For specific applications, it may be more suitable to use the ID API or the VFS API.

Operations on buckets

This group of functions performs operations on buckets: listing, creation, etc.

REST API bucket functions

• dpl_list_all_my_buckets() Lists all the caller's buckets.
• dpl_make_bucket() Creates a bucket.
• dpl_list_bucket() Lists the content of a bucket.

REST API bucket input parameters

• ctx The droplet context.
• location_constraint Creates a bucket with specific location constraints.
• bucket A container for stored objects.
• canned_acl Simplified access control list setting.
• prefix A character or string at the start of an object name.
• delimiter A character or string at the end of an object name.

REST API bucket output parameters

• dpl_status_t Return code for function status (errors/success).
• vecp A vector of strings containing bucket names.
• objectsp List of objects.
• common_prefixesp A prefix that extends past a delimiter, typically involving a path with a separator.

REST API bucket prototypes

#include <droplet.h>
dpl_status_t 
dpl_list_all_my_buckets(dpl_ctx_t *ctx, 
                        dpl_vec_t **vecp);

dpl_status_t 
dpl_make_bucket(dpl_ctx_t *ctx, 
                char *bucket, 
                dpl_location_constraint_t location_constraint, 
                dpl_canned_acl_t canned_acl);

dpl_status_t
dpl_list_bucket(dpl_ctx_t *ctx, 
                char *bucket, 
                char *prefix, 
                char *delimiter, 
                dpl_vec_t **objectsp,
                dpl_vec_t **common_prefixesp);

dpl_status_t 
dpl_deletebucket(dpl_ctx_t *ctx, 
                 char *bucket);

Operations on objects

REST API object functions

• dpl_put() Adds objects to a bucket.
• dpl_put_buffered() Adds objects to a bucket from a buffered input stream.
• dpl_get() Returns objects from storage.
• dpl_get_buffered() Returns objects from a bucket to a buffered output stream.
• dpl_delete() Marks objects for deletion.
• dpl_head() Returns metadata from object headers.

REST API object input parameters

• resource Resource name of the object.
• subresource Component of the object.
• metadata Metadata of the object.
• data_buf The object body.
• data_len The object length.
• condition Condition for returning an object or its header.
• header_func Callback function for every header found in the HTTP response.
• buffer_func Callback function for every chunk of data in the HTTP response.
• cb_arg User-defined callback argument (closure).

REST API object output parameters

• connp Returns connection handles. Caller must free resource after use by calling dpl_conn_release() or dpl_conn_terminate().
• data_bufp Returns object body. Caller must release resource after use by calling dpl_free().
• data_lenp Returns object length.
• metadatap Returns object metadata. Caller must release resource after use by calling dpl_dict_free().

REST API object prototypes

dpl_status_t 
dpl_post(dpl_ctx_t *ctx, 
         char *bucket, 
         char *resource, 
         char *subresource, 
         dpl_option_t *option,
         dpl_ftype_t object_type, 
         dpl_dict_t *metadata, 
         dpl_sysmd_t *sysmd, 
         char *data_buf, 
         u_int data_len, 
         dpl_dict_t *query_params, 
         char **resource_idp);

dpl_status_t 
dpl_post_buffered(dpl_ctx_t *ctx, 
                  char *bucket, 
                  char *resource, 
                  char *subresource, 
                  dpl_option_t *option,
                  dpl_ftype_t object_type, 
                  dpl_dict_t *metadata,
                  dpl_sysmd_t *sysmd, 
                  u_int data_len, 
                  dpl_dict_t *query_params, 
                  dpl_conn_t **connp);

dpl_status_t 
dpl_put(dpl_ctx_t *ctx, 
        char *bucket, 
        char *resource, 
        char *subresource,
        dpl_option_t *option, 
        dpl_ftype_t object_type,  
        dpl_dict_t *metadata, 
        dpl_sysmd_t *sysmd,  
        char *data_buf, 
        u_int data_len);

dpl_status_t 
dpl_put_buffered(dpl_ctx_t *ctx, 
                 char *bucket, 
                 char *resource, 
                 char *subresource,
                 dpl_option_t *option,  
                 dpl_ftype_t object_type, 
                 dpl_dict_t *metadata, 
                 dpl_sysmd_t *sysmd,  
                 u_int data_len, 
                 dpl_conn_t **connp);

dpl_status_t 
dpl_get(dpl_ctx_t *ctx, 
        char *bucket, 
        char *resource, 
        char *subresource, 
        dpl_option_t *option, 
        dpl_ftype_t object_type, 
        dpl_condition_t *condition, 
        char **data_bufp, 
        u_int *data_lenp, 
        dpl_dict_t **metadatap,
        dpl_sysmd_t *sysmdp);

dpl_status_t 
dpl_get_range(dpl_ctx_t *ctx, 
              char *bucket, 
              char *resource, 
              char *subresource, 
              dpl_option_t *option, 
              dpl_ftype_t object_type, 
              dpl_condition_t *condition, 
              dpl_range_t *range, 
              char **data_bufp, 
              unsigned int *data_lenp, 
              dpl_dict_t **metadatap, 
              dpl_sysmd_t *sysmdp);

dpl_status_t 
dpl_get_buffered(dpl_ctx_t *ctx, 
                 char *bucket, 
                 char *resource, 
                 char *subresource,
                 dpl_option_t *option, 
                 dpl_ftype_t object_type,  
                 dpl_condition_t *condition, 
                 dpl_metadatum_func_t metadatum_func, 
                 dpl_dict_t **metadatap,
                 dpl_sysmd_t *sysmdp, 
                 dpl_buffer_func_t buffer_func, 
                 void *cb_arg);

dpl_status_t 
dpl_get_range_buffered(dpl_ctx_t *ctx, 
                       char *bucket, 
                       char *resource, 
                       char *subresource, 
                       dpl_option_t *option
                       dpl_ftype_t object_type, 
                       dpl_condition_t *condition, 
                       dpl_range_t *range, 
                       dpl_metadatum_func_t metadatum_func,                                                      
                       dpl_dict_t **metadatap, 
                       dpl_sysmd_t *sysmdp, 
                       dpl_buffer_func_t buffer_func, 
                       void *cb_arg);

dpl_status_t 
dpl_head(dpl_ctx_t *ctx, 
         char *bucket, 
         char *resource, 
         char *subresource, 
         dpl_option_t *option
         dpl_condition_t *condition, 
         dpl_dict_t **metadatap,
         dpl_sysmd_t *sysmdp);

dpl_status_t 
dpl_head_all(dpl_ctx_t *ctx, 
             char *bucket, 
             char *resource, 
             char *subresource, 
             dpl_option_t *option
             dpl_condition_t *condition, 
             dpl_dict_t **metadatap);

dpl_status_t 
dpl_delete(dpl_ctx_t *ctx, 
           char *bucket, 
           char *resource, 
           char *subresource);

dpl_status_t dpl_genurl(dpl_ctx_t *ctx, 
                        char *bucket, 
                        char *resource, 
                        char *subresource, 
                        dpl_option_t *option,
                        time_t expires, 
                        char *buf, 
                        u_int len, 
                        u_int *lenp);

dpl_status_t 
dpl_copy(dpl_ctx_t *ctx, 
         char *src_bucket, 
         char *src_resource, 
         char *src_subresource, 
         char *dst_bucket, 
         char *dst_resource, 
         char *dst_subresource, 
         dpl_option_t *option,
         dpl_ftype_t object_type, 
         dpl_copy_directive_t copy_directive, 
         dpl_dict_t *metadata, 
         dpl_sysmd_t *sysmd, 
         dpl_condition_t *condition);

dpl_status_t 
dpl_get_resource_id(dpl_ctx_t *ctx, 
                    char *bucket, 
                    char *resource, 
                    char **resource_idp);