Documentation for documents

create

Overview

Allows to create a new document and add it to the specified entity.

As all others, this method requires authentication. To understand how to retrieve the authentication token, refer to the Login documentation page.

Request

endpoint: /api/v1/documents.[format]
http method: POST

format must be either json or xml

Required Parameters

entity_id: ID of the entity to add the document to, as obtained by the entities/index api call.
document[document_type_dc_identifier]: Identifier of the document type
document[data]: File to be attached to this document
document[dc_subject]: Subject describing this document
document[dc_title]: Title of the document
document[dc_description]: Description of this document
document[is_private]: Sets this document as private (document doesn't automatically leave the entity, even in case of pending board invitations that would make that happen. Allowed values: true or false

Furthermore, for each required metadata (depends on the document_type) you need to provide a valid value in the following manner:

document[metadata][metadata_name] : [wanted_value]

Replace metadata_name with the actual name of the required metadata you want to set, and wanted_value with the actual value.

Please note that some fields (i.e. date fields) might require a specific format to be accepted.

Optional Parameters

The following optional attributes are accepted:

document[dc_date]: Date of creation of the document, defaults to now
document[file_name]: File name of the attachment, defaults to the actual attachment file name.

Furthermore, for each optional metadata field, you can add a value with the following syntax:

document[metadata][optional_metadata_name] : [wanted_value]

Replace optional_metadata_name with the actual name of the required metadata you want to set, and wanted_value with the actual value.

Response

Response is a list of the attributes of the document newly created, or an array containing the errors encountered.

id: unique identifier of this document
file_name: file name
file_path: PATH where the document attachment is downloadable
document_type_dc_identifier: Unique identifier of the document type
producer_id: ID of the entity that has uploaded this document
data_file_name: Original file name as uploaded
data_file_size: Size of the attachment
data_content_type: MIME/type of the attachment
dc_creator: Name of the producer entity
is_private: True if the document is private
metadata: Hash of the metadata associated with the document

This is a sample response in JSON format:

{
    "document": {
        "id": 300,
        "file_name": "4588_001.pdf",
        "file_path": "http://localhost:3000/000/000/300/original/4588_001.pdf?1369148105",
        "document_type_dc_identifier": "DT:00183",
        "producer_id": 13,
        "data_file_name": "4588_001.pdf",
        "data_content_type": "application/pdf",
        "data_file_size": 36413,
        "dc_creator": "Producer",
        "is_private": false,
        "metadata": {
            "month_reference": "1",
            "month": "1",
            "year": "2013"
        }
    }
}

Examples

In each sample below, you have to substitute values between angular brackets (< and >) with the correct input data.

cUrl

curl -H "Authorization: Token token=<auth_token>" https://www.myo.io/api/v1/documents.json -F 'entity_id=<entity_id>' -F "document[document_type_dc_identifier]=<document_type_dc_identifier>" -F "document[dc_subject]=<subject>" -F "document[dc_title]=<title>" -F "document[dc_description]=<description>" -F "document[is_private]=<true or false>" -F "document[metadata][<my_metadata_name>]=<my_metadata_value>" -F document[data]=@<file_name_including_path>

Ruby (with rest_client)

require 'rest_client'
RestClient::Request.new(:method => "post", :url => 'https://www.myo.io/api/v1/documents.json', 
                        :payload => {:entity_id => <entity_id>, 'document[document_type_dc_identifier]' => <document_type_id>, 'document[dc_subject]' => <subject>,'document[dc_title]' => <title>,'document[dc_description]' => <description>, 'document[is_private]' => <true or false>, 'document[data]' => File.new("<path_to_you_file>", 'rb'), 'document[metadata][<my_metadata_name>]' => <my_metadata_value>}, 
                        :headers => { :accept => :json, :content_type => :json, :'Authorization' => "Token token=<auth_token>"}).execute

API Operations