forked from dropbox/dropbox-api-spec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
files.stone
1560 lines (1231 loc) · 50.4 KB
/
files.stone
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
namespace files
"This namespace contains endpoints and data types for basic file operations."
import async
import auth
import common
import users_common
import properties
alias Id = String(min_length=1)
alias Path = String(pattern="/(.|[\\r\\n])*")
alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)")
alias PathR = String(pattern="(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)") # A path that can be the root path ("").
alias Rev = String(min_length=9, pattern="[0-9a-f]+") # TODO: Change pattern to "rev:[0-9a-f]{9,}"
alias ListFolderCursor = String(min_length=1)
alias ReadPath = String(pattern="(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")
alias WritePath = String(pattern="(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)")
alias Sha256HexHash = String(min_length=64, max_length=64)
#
# Metadata definitions and route
#
struct Metadata
"Metadata for a file or folder."
union_closed
file FileMetadata
folder FolderMetadata
deleted DeletedMetadata # Used by list_folder* and search
name String
"The last component of the path (including extension).
This never contains a slash."
path_lower String?
"The lowercased full path in the user's Dropbox. This always starts with a slash.
This field will be null if the file or folder is not mounted."
path_display String?
"The cased path to be used for display purposes only. In rare instances the casing will not
correctly match the user's filesystem, but this behavior will match the path provided in
the Core API v1, and at least the last path component will have the correct casing. Changes
to only the casing of paths won't be returned by :route:`list_folder/continue`. This field
will be null if the file or folder is not mounted."
parent_shared_folder_id common.SharedFolderId?
"Deprecated. Please use :field:`FileSharingInfo.parent_shared_folder_id`
or :field:`FolderSharingInfo.parent_shared_folder_id` instead."
example default
file = default
example folder_metadata
folder = default
struct SharingInfo
"Sharing info for a file or folder."
read_only Boolean
"True if the file or folder is inside a read-only shared folder."
example default
read_only = false
struct FileSharingInfo extends SharingInfo
"Sharing info for a file which is contained by a shared folder."
parent_shared_folder_id common.SharedFolderId
"ID of shared folder that holds this file."
modified_by users_common.AccountId?
"The last user who modified the file. This field will be null if
the user's account has been deleted."
example default
read_only = true
parent_shared_folder_id = "84528192421"
modified_by = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
struct FolderSharingInfo extends SharingInfo
"Sharing info for a folder which is contained in a shared folder or is a
shared folder mount point."
parent_shared_folder_id common.SharedFolderId?
"Set if the folder is contained by a shared folder."
shared_folder_id common.SharedFolderId?
"If this folder is a shared folder mount point, the ID of the shared
folder mounted at this location."
traverse_only Boolean = false
"Specifies that the folder can only be traversed and the user can only see
a limited subset of the contents of this folder because they don't have
read access to this folder. They do, however, have access to some sub folder."
no_access Boolean = false
"Specifies that the folder cannot be accessed by the user."
example default
"Folder inside a shared folder."
read_only = false
parent_shared_folder_id = "84528192421"
example shared_folder
"Read-only shared folder mount point."
read_only = true
shared_folder_id = "84528192421"
struct Dimensions
"Dimensions for a photo or video."
height UInt64
"Height of the photo/video."
width UInt64
"Width of the photo/video."
example default
height = 768
width = 1024
struct GpsCoordinates
"GPS coordinates for a photo or video."
latitude Float64
"Latitude of the GPS coordinates."
longitude Float64
"Longitude of the GPS coordinates."
example default
latitude = 37.7833
longitude = 122.4167
struct MediaMetadata
"Metadata for a photo or video."
union_closed
photo PhotoMetadata
video VideoMetadata
dimensions Dimensions?
"Dimension of the photo/video."
location GpsCoordinates?
"The GPS coordinate of the photo/video."
time_taken common.DropboxTimestamp?
"The timestamp when the photo/video is taken."
struct PhotoMetadata extends MediaMetadata
"Metadata for a photo."
example default
dimensions = default
location = default
time_taken = "2015-05-12T15:50:38Z"
struct VideoMetadata extends MediaMetadata
"Metadata for a video."
duration UInt64?
"The duration of the video in milliseconds."
example default
dimensions = default
location = default
time_taken = "2015-05-12T15:50:38Z"
duration = 1000
union_closed MediaInfo
pending
"Indicate the photo/video is still under processing and metadata is
not available yet."
metadata MediaMetadata
"The metadata for the photo/video."
struct FileMetadata extends Metadata
id Id
"A unique identifier for the file."
client_modified common.DropboxTimestamp
"For files, this is the modification time set by the desktop client
when the file was added to Dropbox. Since this time is not verified
(the Dropbox server stores whatever the desktop client sends up), this
should only be used for display purposes (such as sorting) and not,
for example, to determine if a file has changed or not."
server_modified common.DropboxTimestamp
"The last time the file was modified on Dropbox."
rev Rev
"A unique identifier for the current revision of a file. This field is
the same rev as elsewhere in the API and can be used to detect changes
and avoid conflicts."
size UInt64
"The file size in bytes."
media_info MediaInfo?
"Additional information if the file is a photo or video."
sharing_info FileSharingInfo?
"Set if this file is contained in a shared folder."
property_groups List(properties.PropertyGroup)?
"Additional information if the file has custom properties with the
property template specified."
has_explicit_shared_members Boolean?
"This flag will only be present if include_has_explicit_shared_members
is true in :route:`list_folder` or :route:`get_metadata`. If this
flag is present, it will be true if this file has any explicit shared
members. This is different from sharing_info in that this could be true
in the case where a file has explicit members but is not contained within
a shared folder."
content_hash Sha256HexHash?
"A hash of the file content. This field can be used to verify data integrity. For more
information see our :link:`Content hash /developers/reference/content-hash` page."
example default
id = "id:a4ayc_80_OEAAAAAAAAAXw"
name = "Prime_Numbers.txt"
path_lower = "/homework/math/prime_numbers.txt"
path_display = "/Homework/math/Prime_Numbers.txt"
sharing_info = default
client_modified = "2015-05-12T15:50:38Z"
server_modified = "2015-05-12T15:50:38Z"
rev = "a1c10ce0dd78"
size = 7212
property_groups = [default]
has_explicit_shared_members = false
content_hash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
struct FolderMetadata extends Metadata
id Id
"A unique identifier for the folder."
shared_folder_id common.SharedFolderId?
"Deprecated. Please use :field:`sharing_info` instead."
sharing_info FolderSharingInfo?
"Set if the folder is contained in a shared folder or is a shared folder mount point."
property_groups List(properties.PropertyGroup)?
"Additional information if the file has custom properties with the
property template specified."
example default
id = "id:a4ayc_80_OEAAAAAAAAAXz"
path_lower = "/homework/math"
path_display = "/Homework/math"
name = "math"
sharing_info = default
property_groups = [default]
struct DeletedMetadata extends Metadata
"Indicates that there used to be a file or folder at this path, but it no longer exists."
# TODO: Do we care about whether it's a deleted file or folder?
# TODO: Add the mtime when it's been deleted? And the rev???
example default
path_lower = "/homework/math/pi.txt"
path_display = "/Homework/math/pi.txt"
name = "pi.txt"
union_closed GetMetadataError
path LookupError
struct GetMetadataArg
path ReadPath
"The path of a file or folder on Dropbox."
include_media_info Boolean = false
"If true, :field:`FileMetadata.media_info` is set for photo and video."
include_deleted Boolean = false
"If true, :type:`DeletedMetadata` will be returned for deleted file or
folder, otherwise :field:`LookupError.not_found` will be returned."
include_has_explicit_shared_members Boolean = false
"If true, the results will include a flag for each file indicating whether or not
that file has any explicit members."
example default
path = "/Homework/math"
example id
path = "id:a4ayc_80_OEAAAAAAAAAYa"
example rev
path = "rev:a1c10ce0dd78"
route get_metadata (GetMetadataArg, Metadata, GetMetadataError)
"Returns the metadata for a file or folder.
Note: Metadata for the root folder is unsupported."
attrs
owner = "dev-plat"
allow_app_folder_app = true
takes_path_root = true
#
# List folder routes
#
struct ListFolderLongpollArg
cursor ListFolderCursor
"A cursor as returned by :route:`list_folder` or :route:`list_folder/continue`. Cursors
retrieved by setting :field:`ListFolderArg.include_media_info` to :val:`true` are not
supported."
timeout UInt64(min_value=30, max_value=480) = 30
"A timeout in seconds. The request will block for at most this length
of time, plus up to 90 seconds of random jitter added to avoid the
thundering herd problem. Care should be taken when using this
parameter, as some network infrastructure does not support long
timeouts."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
struct ListFolderLongpollResult
changes Boolean
"Indicates whether new changes are available. If true, call
:route:`list_folder/continue` to retrieve the changes."
backoff UInt64?
"If present, backoff for at least this many seconds before calling
:route:`list_folder/longpoll` again."
example default
changes = true
union ListFolderLongpollError
reset
"Indicates that the cursor has been invalidated. Call
:route:`list_folder` to obtain a new cursor."
route list_folder/longpoll (ListFolderLongpollArg, ListFolderLongpollResult, ListFolderLongpollError)
"A longpoll endpoint to wait for changes on an account. In conjunction with
:route:`list_folder/continue`, this call gives you a low-latency way to
monitor an account for file changes. The connection will block until there
are changes available or a timeout occurs. This endpoint is useful mostly
for client-side apps. If you're looking for server-side notifications,
check out our
:link:`webhooks documentation https://www.dropbox.com/developers/reference/webhooks`."
attrs
host = "notify"
auth = "noauth"
owner = "dev-plat"
allow_app_folder_app = true
struct ListFolderArg
path PathR
"The path to the folder you want to see the contents of."
recursive Boolean = false
"If true, the list folder operation will be applied recursively to all subfolders
and the response will contain contents of all subfolders."
include_media_info Boolean = false
"If true, :field:`FileMetadata.media_info` is set for photo and video."
include_deleted Boolean = false
"If true, the results will include entries for files and folders that used to exist but were deleted."
include_has_explicit_shared_members Boolean = false
"If true, the results will include a flag for each file indicating whether or not
that file has any explicit members."
example default
path = "/Homework/math"
recursive = false
struct ListFolderResult
entries List(Metadata)
"The files and (direct) subfolders in the folder."
cursor ListFolderCursor
"Pass the cursor into :route:`list_folder/continue` to see what's
changed in the folder since your previous query."
has_more Boolean
"If true, then there are more entries available. Pass the
cursor to :route:`list_folder/continue` to retrieve the rest."
example default
entries = [default, folder_metadata]
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
has_more = false
union ListFolderError
path LookupError
route list_folder (ListFolderArg, ListFolderResult, ListFolderError)
"Starts returning the contents of a folder. If the result's :field:`ListFolderResult.has_more`
field is :val:`true`, call :route:`list_folder/continue` with the returned
:field:`ListFolderResult.cursor` to retrieve more entries.
If you're using :field:`ListFolderArg.recursive` set to :val:`true` to keep a local cache of
the contents of a Dropbox account, iterate through each entry in order and process them as
follows to keep your local state in sync:
For each :type:`FileMetadata`, store the new entry at the given path in your local state. If the
required parent folders don't exist yet, create them. If there's already something else at the
given path, replace it and remove all its children.
For each :type:`FolderMetadata`, store the new entry at the given path in your local state. If
the required parent folders don't exist yet, create them. If there's already something else at
the given path, replace it but leave the children as they are. Check the new entry's
:field:`FolderSharingInfo.read_only` and set all its children's read-only statuses to match.
For each :type:`DeletedMetadata`, if your local state has something at the given path, remove it
and all its children. If there's nothing at the given path, ignore this entry.
Note: :type:`auth.RateLimitError` may be returned if multiple :route:`list_folder` or
:route:`list_folder/continue` calls with same parameters are made simultaneously by same
API app for same user. If your app implements retry logic, please hold off the retry until
the previous request finishes."
attrs
owner = "dev-plat"
allow_app_folder_app = true
struct ListFolderContinueArg
cursor ListFolderCursor
"The cursor returned by your last call to :route:`list_folder` or
:route:`list_folder/continue`."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
union ListFolderContinueError
path LookupError
reset
"Indicates that the cursor has been invalidated. Call
:route:`list_folder` to obtain a new cursor."
route list_folder/continue (ListFolderContinueArg, ListFolderResult, ListFolderContinueError)
"Once a cursor has been retrieved from :route:`list_folder`, use this to paginate through all
files and retrieve updates to the folder, following the same rules as documented for
:route:`list_folder`."
attrs
owner = "dev-plat"
allow_app_folder_app = true
struct ListFolderGetLatestCursorResult
cursor ListFolderCursor
"Pass the cursor into :route:`list_folder/continue` to see what's
changed in the folder since your previous query."
example default
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
route list_folder/get_latest_cursor (ListFolderArg, ListFolderGetLatestCursorResult, ListFolderError)
"A way to quickly get a cursor for the folder's state. Unlike :route:`list_folder`,
:route:`list_folder/get_latest_cursor` doesn't return any entries. This endpoint is for app
which only needs to know about new files and modifications and doesn't need to know about
files that already exist in Dropbox."
attrs
owner = "dev-plat"
allow_app_folder_app = true
#
# Download
#
union DownloadError
path LookupError
struct DownloadArg
path ReadPath
"The path of the file to download."
rev Rev?
"Deprecated. Please specify revision in :field:`path` instead."
example default
path = "/Homework/math/Prime_Numbers.txt"
example id
path = "id:a4ayc_80_OEAAAAAAAAAYa"
example rev
path = "rev:a1c10ce0dd78"
route download (DownloadArg, FileMetadata, DownloadError)
"Download a file from a user's Dropbox."
attrs
host = "content"
style = "download"
owner = "dev-plat"
allow_app_folder_app = true
#
# Upload Routes
#
# Errors
struct UploadWriteFailed
reason WriteError
"The reason why the file couldn't be saved."
upload_session_id String
"The upload session ID; this may be used to retry the commit."
union UploadError
path UploadWriteFailed
"Unable to save the uploaded contents to a file."
struct UploadSessionOffsetError
correct_offset UInt64
"The offset up to which data has been collected."
union UploadSessionLookupError
not_found
"The upload session ID was not found or has expired. Upload sessions are
valid for 48 hours."
incorrect_offset UploadSessionOffsetError
"The specified offset was incorrect. See the value for the
correct offset. This error may occur when a previous request
was received and processed successfully but the client did not
receive the response, e.g. due to a network error."
closed
"You are attempting to append data to an upload session that
has alread been closed (i.e. committed)."
not_closed
"The session must be closed before calling upload_session/finish_batch."
union UploadSessionFinishError
lookup_failed UploadSessionLookupError
"The session arguments are incorrect; the value explains the reason."
path WriteError
"Unable to save the uploaded contents to a file."
too_many_shared_folder_targets
"The batch request commits files into too many different shared folders.
Please limit your batch request to files contained in a single shared folder."
too_many_write_operations
"There are too many write operations happening in the user's Dropbox. You should
retry uploading this file."
# Req/Resp
struct UploadSessionStartArg
close Boolean = false
"If true, the current session will be closed, at which point you won't
be able to call :route:`upload_session/append_v2` anymore with the
current session."
example with_close
close = false
struct UploadSessionStartResult
session_id String
"A unique identifier for the upload session. Pass this to
:route:`upload_session/append_v2` and
:route:`upload_session/finish`."
example default
session_id = "1234faaf0678bcde"
route upload_session/start (UploadSessionStartArg, UploadSessionStartResult, Void)
"Upload sessions allow you to upload a single file in one or more
requests, for example where the size of the file is greater than 150
MB. This call starts a new upload session with the given data. You
can then use :route:`upload_session/append_v2` to add more data and
:route:`upload_session/finish` to save all the data to a file in
Dropbox.
A single request should not upload more than 150 MB.
An upload session can be used for a maximum of 48 hours. Attempting
to use an :field:`UploadSessionStartResult.session_id` with
:route:`upload_session/append_v2` or :route:`upload_session/finish` more
than 48 hours after its creation will return a
:field:`UploadSessionLookupError.not_found`."
attrs
host = "content"
style = "upload"
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
struct UploadSessionAppendArg
cursor UploadSessionCursor
"Contains the upload session ID and the offset."
close Boolean = false
"If true, the current session will be closed, at which point
you won't be able to call :route:`upload_session/append_v2`
anymore with the current session."
example default
cursor = default
route upload_session/append_v2 (UploadSessionAppendArg, Void, UploadSessionLookupError)
"Append more data to an upload session.
When the parameter close is set, this call will close the session.
A single request should not upload more than 150 MB."
attrs
host = "content"
style = "upload"
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
struct UploadSessionCursor
session_id String
"The upload session ID (returned by :route:`upload_session/start`)."
offset UInt64
"The amount of data that has been uploaded so far. We use this to make
sure upload data isn't lost or duplicated in the event of a network
error."
example default
session_id = "1234faaf0678bcde"
offset = 0
route upload_session/append (UploadSessionCursor, Void, UploadSessionLookupError) deprecated by upload_session/append_v2
"Append more data to an upload session.
A single request should not upload more than 150 MB."
attrs
host = "content"
style = "upload"
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
union_closed WriteMode
"Your intent when writing a file to some path. This is used to determine
what constitutes a conflict and what the autorename strategy is.
In some situations, the conflict behavior is identical:
(a) If the target path doesn't contain anything, the file is always written;
no conflict.
(b) If the target path contains a folder, it's always a conflict.
(c) If the target path contains a file with identical contents, nothing gets
written; no conflict.
The conflict checking differs in the case where there's a file at the target
path with contents different from the contents you're trying to write."
add
"Do not overwrite an existing file if there is a conflict. The
autorename strategy is to append a number to the file name. For example,
\"document.txt\" might become \"document (2).txt\"."
overwrite
"Always overwrite the existing file. The autorename
strategy is the same as it is for :field:`add`."
update Rev
"Overwrite if the given \"rev\" matches the existing file's \"rev\".
The autorename strategy is to append the string \"conflicted copy\"
to the file name. For example, \"document.txt\" might become
\"document (conflicted copy).txt\" or \"document (Panda's conflicted copy).txt\"."
example default
add = null
example overwriting
overwrite = null
example with_revision
update = "a1c10ce0dd78"
struct CommitInfo
path WritePath
"Path in the user's Dropbox to save the file."
mode WriteMode = add
"Selects what to do if the file already exists."
autorename Boolean = false
"If there's a conflict, as determined by :field:`mode`, have the Dropbox
server try to autorename the file to avoid conflict."
client_modified common.DropboxTimestamp?
"The value to store as the :field:`client_modified` timestamp. Dropbox
automatically records the time at which the file was written to the
Dropbox servers. It can also record an additional timestamp, provided
by Dropbox desktop clients, mobile clients, and API apps of when the
file was actually created or modified."
mute Boolean = false
"Normally, users are made aware of any file modifications in their
Dropbox account via notifications in the client software. If
:val:`true`, this tells the clients that this modification shouldn't
result in a user notification."
example default
path = "/Homework/math/Matrices.txt"
autorename = true
example update
path = "/Homework/math/Matrices.txt"
mode = with_revision
autorename = false
struct UploadSessionFinishArg
cursor UploadSessionCursor
"Contains the upload session ID and the offset."
commit CommitInfo
"Contains the path and other optional modifiers for the commit."
example default
cursor = default
commit = default
example update
cursor = default
commit = update
route upload_session/finish (UploadSessionFinishArg, FileMetadata, UploadSessionFinishError)
"Finish an upload session and save the uploaded data to the given file
path.
A single request should not upload more than 150 MB."
attrs
host = "content"
style = "upload"
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
route upload (CommitInfo, FileMetadata, UploadError)
"Create a new file with the contents provided in the request.
Do not use this to upload a file larger than 150 MB. Instead, create an
upload session with :route:`upload_session/start`."
attrs
host = "content"
style = "upload"
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
takes_path_root = true
#
# Batch Upload
#
struct UploadSessionFinishBatchArg
entries List(UploadSessionFinishArg, max_items=1000)
"Commit information for each file in the batch."
example default
entries = [default]
struct UploadSessionFinishBatchResult
entries List(UploadSessionFinishBatchResultEntry)
"Commit result for each file in the batch."
example default
entries = [default]
union_closed UploadSessionFinishBatchResultEntry
success FileMetadata
failure UploadSessionFinishError
example default
success = default
union_closed UploadSessionFinishBatchJobStatus extends async.PollResultBase
complete UploadSessionFinishBatchResult
"The :route:`upload_session/finish_batch` has finished."
example default
complete = default
union UploadSessionFinishBatchLaunch extends async.LaunchResultBase
"Result returned by :route:`upload_session/finish_batch` that may either launch an
asynchronous job or complete synchronously."
complete UploadSessionFinishBatchResult
example complete
complete = default
example async_job_id
async_job_id = "34g93hh34h04y384084"
route upload_session/finish_batch (UploadSessionFinishBatchArg, UploadSessionFinishBatchLaunch, Void)
"This route helps you commit many files at once into a user's Dropbox. Use
:route:`upload_session/start` and :route:`upload_session/append_v2` to
upload file contents. We recommend uploading many files in parallel to increase
throughput. Once the file contents have been uploaded, rather than calling
:route:`upload_session/finish`, use this route to finish all your upload sessions
in a single request.
:field:`UploadSessionStartArg.close` or :field:`UploadSessionAppendArg.close`
needs to be true for the last
:route:`upload_session/start` or :route:`upload_session/append_v2` call.
This route will return a job_id immediately and do the async commit job in background.
Use :route:`upload_session/finish_batch/check` to check the job status.
For the same account, this route should be executed serially. That means you should not start
the next job before current job finishes. We allow up to 1000 entries in a single request."
attrs
owner = "dev-plat"
feature = "upload_api_rate_limit"
allow_app_folder_app = true
route upload_session/finish_batch/check(async.PollArg, UploadSessionFinishBatchJobStatus, async.PollError)
"Returns the status of an asynchronous job for :route:`upload_session/finish_batch`. If
success, it returns list of result for each entry."
attrs
owner = "dev-plat"
allow_app_folder_app = true
#
# Search
#
union_closed SearchMode
filename
"Search file and folder names."
filename_and_content
"Search file and folder names as well as file contents."
deleted_filename
"Search for deleted file and folder names."
example default
filename_and_content = null
example name_only
filename = null
example deleted_names
deleted_filename = null
struct SearchArg
path PathR
"The path in the user's Dropbox to search. Should probably be
a folder."
query String
"The string to search for. The search string is split on spaces into
multiple tokens. For file name searching, the last token is used for
prefix matching (i.e. \"bat c\" matches \"bat cave\" but not \"batman
car\")."
start UInt64 = 0
"The starting index within the search results (used for paging)."
max_results UInt64(min_value=1, max_value=1000) = 100
"The maximum number of search results to return."
mode SearchMode = filename
"The search mode (filename, filename_and_content, or deleted_filename).
Note that searching file content is only available for Dropbox Business
accounts."
example default
path = ""
query = "prime numbers"
union_closed SearchMatchType
"Indicates what type of match was found for a given item."
filename
"This item was matched on its file or folder name."
content
"This item was matched based on its file contents."
both
"This item was matched based on both its contents and its file name."
example default
content = null
struct SearchMatch
match_type SearchMatchType
"The type of the match."
metadata Metadata
"The metadata for the matched file or folder."
example default
match_type = default
metadata = default
struct SearchResult
matches List(SearchMatch)
"A list (possibly empty) of matches for the query."
more Boolean
"Used for paging. If true, indicates there is another page of results
available that can be fetched by calling :route:`search` again."
start UInt64
"Used for paging. Value to set the start argument to when calling
:route:`search` to fetch the next page of results."
example default
matches = [default]
more = false
start = 1
union SearchError
path LookupError
route search (SearchArg, SearchResult, SearchError)
"Searches for files and folders.
Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing."
attrs
owner = "dev-plat"
allow_app_folder_app = true
#
# Errors shared by various operations
#
alias MalformedPathError = String? # TODO: Maybe a user_message-like thing?
union LookupError
malformed_path MalformedPathError
not_found
"There is nothing at the given path."
not_file
"We were expecting a file, but the given path refers to something that isn't a file."
not_folder
"We were expecting a folder, but the given path refers to something that isn't a folder."
restricted_content
"The file cannot be transferred because the content is restricted. For example,
sometimes there are legal restrictions due to copyright claims."
union WriteError
malformed_path MalformedPathError
conflict WriteConflictError
"Couldn't write to the target path because there was something in the way."
no_write_permission
"The user doesn't have permissions to write to the target location."
insufficient_space
"The user doesn't have enough available space (bytes) to write more data."
disallowed_name
"Dropbox will not save the file or folder because of its name."
team_folder
"This endpoint cannot modify or delete team folders."
union WriteConflictError
file
"There's a file in the way."
folder
"There's a folder in the way."
file_ancestor
"There's a file at an ancestor path, so we couldn't create the required parent folders."
#
# Create folder
#
struct CreateFolderArg
path WritePath
"Path in the user's Dropbox to create."
autorename Boolean = false
"If there's a conflict, have the Dropbox server try to autorename
the folder to avoid the conflict."
example default
path = "/Homework/math"
union_closed CreateFolderError
path WriteError
route create_folder (CreateFolderArg, FolderMetadata, CreateFolderError)
"Create a folder at a given path."
attrs
owner = "dev-plat"
allow_app_folder_app = true
#
# Delete
#
struct DeleteArg
path WritePath
"Path in the user's Dropbox to delete."
example delete
path = "/Homework/math/Prime_Numbers.txt"
union DeleteError
path_lookup LookupError
path_write WriteError
struct DeleteBatchArg
entries List(DeleteArg)
example default
entries = [delete]
union_closed DeleteBatchResultEntry
success DeleteResult
failure DeleteError
example default
success = default
struct DeleteResult
metadata Metadata
example default
metadata = default
struct DeleteBatchResult
entries List(DeleteBatchResultEntry)
example default
entries = [default]
union DeleteBatchError
too_many_write_operations
"There are too many write operations in user's Dropbox. Please retry
this request."
union DeleteBatchJobStatus extends async.PollResultBase
complete DeleteBatchResult
"The batch delete has finished."
failed DeleteBatchError
"The batch delete has failed."