cmd/bpa-restapi-agent/README.md

   1 ### Running the server
   2 To run the server, follow these simple steps:
   3
   4 ```
   5 go run main.go
   6 ```
   7 Integrated Cloud Native (ICN) RESTful API
   8
   9 This is a Golang application providing a RESTful API to interact with and upload image objects.
  10
  11 The API application source files are in the icn/cmd/bpa-restapi-agent directory.
  12
  13 While the database back-end is extensible, this initial release requires mongodb.
  14
  15 Install
  16
  17 Install and start mongodb. For instructions: https://docs.mongodb.com/manual/installation/
  18
  19 git clone "https://gerrit.akraino.org/r/icn"
  20 cd icn/cmd/bpa-restapi-agent
  21
  22 Run the application
  23 go run main.go
  24
  25 Output without a  config file:
  26
  27 2019/08/22 14:08:41 Error loading config file. Using defaults
  28 2019/08/22 14:08:41 Starting Integrated Cloud Native API
  29
  30 RESTful API usage examples
  31
  32 Sample Post Request
  33
  34 curl -i -F "metadata=<jsonfile;type=application/json" -F file=@/home/<username>/<dir>/jsonfile -X POST http://NODE_IP:9015//baremetalcluster/{owner}/{clustername}/<image_type>
  35
  36 #image type can be binary_image, container_image, or os_image
  37
  38 Example requests and responses:
  39
  40 Create image - POST
  41
  42 #Using a json file called sample.json
  43 #image_length in sample.json can be determined with the command
  44 ls -al <image_file>
  45
  46 Request
  47
  48 curl -i -F "metadata=<sample.json;type=application/json" -F file=@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample.json -X POST http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images
  49
  50 Response
  51
  52 HTTP/1.1 100 Continue
  53
  54 HTTP/1.1 201 Created
  55 Content-Type: application/json
  56 Date: Thu, 22 Aug 2019 22:56:16 GMT
  57 Content-Length: 239
  58
  59 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
  60
  61 #this creates a database entry for the image, and an empty file in the file system
  62
  63 List image - GET
  64
  65 curl -i -X GET http://localhost:9015/v1/baremetalcluster/{owner}/{clustername}/<image_type>/{imgname}
  66
  67
  68 example:
  69 #continuing with our container image from above
  70
  71 Request
  72
  73 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
  74
  75 Response
  76
  77 HTTP/1.1 200 OK
  78 Content-Type: application/json
  79 Date: Thu, 22 Aug 2019 22:57:10 GMT
  80 Content-Length: 239
  81
  82 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
  83
  84 Upload container image - PATCH
  85 Request
  86
  87 curl --request PATCH --data-binary "@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image" http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 0" --header "Expect:" -i
  88
  89
  90 Response
  91
  92 HTTP/1.1 204 No Content
  93 Upload-Offset: 29718177
  94 Date: Thu, 22 Aug 2019 23:19:44 GMT
  95
  96 Check uploaded image - GET
  97
  98 Request
  99
 100 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 101
 102 Response
 103
 104 HTTP/1.1 200 OK
 105 Content-Type: application/json
 106 Date: Fri, 23 Aug 2019 17:12:07 GMT
 107 Content-Length: 245
 108
 109 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":29718177,"image_length":29718177,"upload_complete":true,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
 110
 111 #after the upload, the image_offset is now the same as image_length and upload_complete changed to true
 112 #if upload was incomplete
 113
 114 Resumable upload instructions
 115
 116 Resumable upload -PATCH
 117
 118 #this is the current resumable upload mechanism
 119
 120 Request
 121
 122 curl --request PATCH --data-binary "@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image" http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 0" --header "Expect:" -i --limit-rate 200K
 123
 124 #the above request limits transfer for testing purposes
 125 #'ctl c' out after a few seconds, to stop file transfer
 126 #check image_offset with a GET
 127
 128 Check upload - GET
 129
 130 Request
 131
 132 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 133
 134 Response
 135
 136 HTTP/1.1 200 OK
 137 Content-Type: application/json
 138 Date: Sat, 24 Aug 2019 00:30:00 GMT
 139 Content-Length: 245
 140
 141 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":4079616,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"2"}]}}
 142
 143 #from our response you can see that image_offset is still less than image_length and #upload_complete is still false
 144 #next we use the dd command (no limiting this time)
 145
 146 Request
 147
 148 dd if=/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image skip=4079616 bs=1 | curl --request PATCH --data-binary @- http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 4079616" --header "Expect:" -i
 149
 150 #the request skips already uploaded 4079616 bytes of data
 151
 152 Response
 153
 154 25638561+0 records in
 155 25638561+0 records out
 156 25638561 bytes (26 MB, 24 MiB) copied, 207.954 s, 123 kB/s
 157 HTTP/1.1 204 No Content
 158 Upload-Offset: 29718177
 159 Date: Sat, 24 Aug 2019 00:43:18 GMT
 160
 161 Update image description - PUT
 162
 163 # let's change the tag in description from 1 to latest
 164 # once the  change is made in sample.json (or your json file)
 165
 166 Request
 167
 168 curl -i -F "metadata=<sample.json;type=application/json" -F file=@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample.json -X PUT http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 169
 170 Response
 171
 172 HTTP/1.1 100 Continue
 173
 174 HTTP/1.1 201 Created
 175 Content-Type: application/json
 176 Date: Fri, 23 Aug 2019 17:21:01 GMT
 177 Content-Length: 239
 178
 179 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"2"}]}}
 180
 181 Delete an image - DELETE
 182
 183 Request
 184
 185 curl -i -X DELETE http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 186
 187 Response