How to upload a document?
We will cover the upload a new document endpoint in detail.
It allows you to upload any kind of document (pdf, image, etc...) to your api's storage.
Then you can use it in other endpoints of the API, in your own website or anywhere else.
Upload a new Document of type file
- base url
- https://api.particeep.com/v1/document/{owner_id}/upload
- method
- POST
Step 1 - Upload a document
To upload a document you will need to link it to a User : its owner. In this tutorial we will be using the administrator of the test environment.
His id is bf5788e8-9756-4d18-8b0f-100d7fba17a2
. We need it in the url.
In a real application you should use the id of the connected User or the id of your administrator.
Then we need a file to upload, we will use the Particeep's logo.
Save the file locally to allow your code to acces it
You can upload any number of file, we only add a restriction on the file's size : it must be 12Mo or less
Finally the code :
public static void uploadDocument() {
String url = "https://test-api.particeep.com/v1/document/bf5788e8-9756-4d18-8b0f-100d7fba17a2/upload";
String apiKey = "d6a53e1a-fc8e-4251-9dda-fabbce5f2a2c";
String apiSecret = "9bb3c122-0272-4bed-a632-19d5d52c7b5e";
String dateTime = buildDateHeader();
Map headers = new HashMap();
headers.put("DateTime", dateTime);
headers.put("Authorization", buildAuthorizationHeaderSafe(apiKey, apiSecret, dateTime));
HttpResponse rez = WS.url(url)
.headers(headers)
.files(new WS.FileParam(new File("/path/to/file/logo.png"), "document"))
.post();
System.out.println("status: " + rez.getStatus());
System.out.println("json:" + rez.getString());
}
We are using functions from the previous tutorial to handle security and web requests.
The main point is to send a file in the request body as a form parameter named `document`. Your code need to act like it is submitting a file in a form.
<form action="https://test-api.particeep.com/v1/document/bf5788e8-9756-4d18-8b0f-100d7fba17a2/upload" method="POST">
<input type="file" name="document">
</form>
You should get the following json as a result (or something similar as id are generated)
{
"id": "0ced192a-4d86-48fb-9fdf-3cc98c26aff1",
"created_at": "2017-06-08T13:15:25Z",
"owner_id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
"name": "logo.png",
"content_type": "image/png",
"path": "/",
"doc_type": "FILE",
"locked": false,
"permalink": "https://test-api.particeep.com/document/0ced192a-4d86-48fb-9fdf-3cc98c26aff1"
}
You can add some meta-data on your file while uploading it, like a description. You can also change default values like the file's name.
You can find the detail of every parameters in the api documentation.
Map parameters = new HashMap();
parameters.put("name", "logo_particeep");
parameters.put("description", "a test file");
HttpResponse rez = WS.url(url)
.headers(headers)
.files(new WS.FileParam(new File("/Users/adrien/Downloads/13487.png"), "document"))
.params(parameters)
.post();
You can see that the name has changed and our description is saved.
{
"id": "e34767cd-6f26-4c42-99ea-99363efa6d99",
"created_at": "2017-06-08T13:43:51Z",
"owner_id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
"name": "logo_particeep",
"description": "a test file",
"content_type": "image/png",
"path": "/",
"doc_type": "FILE",
"locked": false,
"permalink": "https://local.particeep.com:9100/document/e34767cd-6f26-4c42-99ea-99363efa6d99"
}
Step 2 - Permalink and security
Once uploaded, you can access your file via 2 ways:
- via the download endpoint.
Its url is like
https://test-api.particeep.com/v1/document/download/{id}
({id}
is the id of the document). This is a secured access, you need to provide your api's credentials to use this endpoint. The target for this endpoint is your own system : your server should use this endpoint. It allows you to carefully take care of who is accessing the document and when, manage access's right etc...
- via the permalink. The permalink is sent back to you in the JSON response. Its url is like
https://test-api.particeep.com/document/{a_uuid}
Note that it doesn't contain the/v1
in the url. That means the access is not filtered by api's credentials.
This allows you to share the document via this link in your email, on social networks or anywhere else. When you share a document via its permalink, anyone can share it again with other people.
It is your responsibility to choose how you share your documents. Be careful as permalinks can be accessed by anybody.
Step 3 - Common use case
We covered only the very basics of the document management in Particeep's API.
We will list some examples of how our users are using the document's upload.
If you want to go further you can follow our tutorial on How to generate PDF document
- Upload images, css and other content to use it in custom page edition. For instance to build your home page in a white label platform.
- Upload Kyc information like id cards to manage investors
- Share documents in a private circle
- Ask company on your platform for monthly reports
- Your idea!