Rest api with curl » History » Version 10

Toshi MARUYAMA, 2019-10-18 13:18
add code class xml/json

1 1 Jean-Philippe Lang
h1. Using the REST API with cURL
2 1 Jean-Philippe Lang
3 1 Jean-Philippe Lang
"curl":http://curl.haxx.se/ is a command-line tool for transferring data using various protocols. It can be used to interact with the Redmine REST API.
4 1 Jean-Philippe Lang
5 3 Jean-Philippe Lang
h2. Using JSON
6 3 Jean-Philippe Lang
7 1 Jean-Philippe Lang
Here is a simple example of a command that can be used to update an issue:
8 1 Jean-Philippe Lang
9 1 Jean-Philippe Lang
<pre>
10 7 Holger Just
curl -v -H "Content-Type: application/json" -X PUT --data-binary "@388.json" -u login:password http://redmine/issues/388.json
11 7 Holger Just
curl -v -H "Content-Type: application/json" -X PUT --data-binary "@388.json" -H "X-Redmine-API-Key: xxxx" http://redmine/issues/388.json
12 1 Jean-Philippe Lang
</pre>
13 1 Jean-Philippe Lang
14 1 Jean-Philippe Lang
The file that contains the data sent to Redmine (388.json in the example above) would look like this:
15 1 Jean-Philippe Lang
16 10 Toshi MARUYAMA
<pre><code class="json">
17 1 Jean-Philippe Lang
{
18 1 Jean-Philippe Lang
  "issue": {
19 1 Jean-Philippe Lang
    "subject": "subject123",
20 1 Jean-Philippe Lang
    "notes": "Changing the subject"
21 1 Jean-Philippe Lang
  }
22 1 Jean-Philippe Lang
}
23 10 Toshi MARUYAMA
</code></pre>
24 2 Jean-Philippe Lang
25 2 Jean-Philippe Lang
Note: it's required to set the @Content-Type@ header according to the format of the data you are sending. It must be set to one the following values:
26 2 Jean-Philippe Lang
* @application/json@
27 1 Jean-Philippe Lang
* @application/xml@
28 3 Jean-Philippe Lang
29 3 Jean-Philippe Lang
h2. Using XML
30 3 Jean-Philippe Lang
31 3 Jean-Philippe Lang
32 3 Jean-Philippe Lang
Here is a simple example of a command that can be used to create an issue with custom fields:
33 3 Jean-Philippe Lang
34 3 Jean-Philippe Lang
<pre>
35 7 Holger Just
curl -v -H "Content-Type: application/xml" -X POST --data-binary "@issue.xml" -u login:password http://redmine/issues.xml
36 7 Holger Just
curl -v -H "Content-Type: application/xml" -X POST --data-binary "@issue.xml" -H "X-Redmine-API-Key: xxxx" http://redmine/issues.xml
37 4 Terence Mill
38 3 Jean-Philippe Lang
</pre>
39 3 Jean-Philippe Lang
40 3 Jean-Philippe Lang
Where issue.xml content is:
41 3 Jean-Philippe Lang
42 10 Toshi MARUYAMA
<pre><code class="xml">
43 3 Jean-Philippe Lang
<?xml version="1.0" encoding="ISO-8859-1" ?>
44 3 Jean-Philippe Lang
<issue>
45 3 Jean-Philippe Lang
  <subject>API custom fields</subject>
46 3 Jean-Philippe Lang
  <project_id>1</project_id>
47 3 Jean-Philippe Lang
  <tracker_id>2</tracker_id>
48 3 Jean-Philippe Lang
  <custom_fields type="array">
49 3 Jean-Philippe Lang
    <custom_field>
50 3 Jean-Philippe Lang
      <id>2</id>
51 3 Jean-Philippe Lang
      <value>Fixed</value>
52 3 Jean-Philippe Lang
    </custom_field>
53 3 Jean-Philippe Lang
    <custom_field>
54 3 Jean-Philippe Lang
      <id>1</id>
55 3 Jean-Philippe Lang
      <value>0.8.2</value>
56 3 Jean-Philippe Lang
    </custom_field>
57 3 Jean-Philippe Lang
  </custom_fields>
58 3 Jean-Philippe Lang
</issue>
59 10 Toshi MARUYAMA
</code></pre>
60 5 Jean-Philippe Lang
61 6 Lucile Quirion
h2. Text formatting
62 6 Lucile Quirion
63 7 Holger Just
If you want to use some text formatting (e.g to update a wiki page on your project), you should make sure to use curl's option @--data-binary@ instead of @--data@ to load the file. Only that way, curl will send newline characters unchanged and will retain all formatting.
64 6 Lucile Quirion
65 6 Lucile Quirion
<pre>curl -v -H "Content-Type: application/xml" -X PUT --data-binary "@wiki.xml" -u login:password http://redmine/projects/foo/wiki/page_test.xml</pre>
66 6 Lucile Quirion
67 6 Lucile Quirion
Where wiki.xml content is:
68 6 Lucile Quirion
69 10 Toshi MARUYAMA
<pre><code class="xml">
70 6 Lucile Quirion
<?xml version="1.0"?>
71 6 Lucile Quirion
<wiki_page>
72 6 Lucile Quirion
<text>
73 6 Lucile Quirion
h1. TITLE
74 6 Lucile Quirion
75 6 Lucile Quirion
 %{font-size:14pt}SUBTITLE%
76 6 Lucile Quirion
</text>
77 6 Lucile Quirion
</wiki_page>
78 10 Toshi MARUYAMA
</code></pre>
79 6 Lucile Quirion
80 5 Jean-Philippe Lang
h2. Attaching files
81 5 Jean-Philippe Lang
82 5 Jean-Philippe Lang
If you want to create an issue with image.png attached, you need to upload this file first:
83 5 Jean-Philippe Lang
84 5 Jean-Philippe Lang
<pre>
85 9 Go MAEDA
curl --data-binary "@image.png" -H "Content-Type: application/octet-stream" -X POST -u login:password http://redmine/uploads.xml?filename=image.png
86 5 Jean-Philippe Lang
87 5 Jean-Philippe Lang
# 201 response
88 5 Jean-Philippe Lang
<upload>
89 5 Jean-Philippe Lang
  <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
90 5 Jean-Philippe Lang
</upload>
91 5 Jean-Philippe Lang
</pre>
92 5 Jean-Philippe Lang
93 5 Jean-Philippe Lang
Then, use the token to create the issue:
94 5 Jean-Philippe Lang
95 5 Jean-Philippe Lang
<pre>
96 8 Holger Just
curl -v -H "Content-Type: application/xml" -X POST --data-binary "@issue.xml" -u login:password http://redmine/issues.xml
97 5 Jean-Philippe Lang
</pre>
98 5 Jean-Philippe Lang
99 5 Jean-Philippe Lang
Where issue.xml content is:
100 5 Jean-Philippe Lang
101 10 Toshi MARUYAMA
<pre><code class="xml">
102 5 Jean-Philippe Lang
<?xml version="1.0" encoding="ISO-8859-1" ?>
103 5 Jean-Philippe Lang
<issue>
104 5 Jean-Philippe Lang
  <subject>Issue with attachment</subject>
105 5 Jean-Philippe Lang
  <project_id>1</project_id>
106 5 Jean-Philippe Lang
  <uploads type="array">
107 5 Jean-Philippe Lang
    <upload>
108 5 Jean-Philippe Lang
      <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
109 5 Jean-Philippe Lang
      <filename>image.png</filename>
110 5 Jean-Philippe Lang
      <content_type>image/png</content_type>
111 5 Jean-Philippe Lang
    </upload>
112 5 Jean-Philippe Lang
  </uploads>
113 5 Jean-Philippe Lang
</issue>
114 10 Toshi MARUYAMA
</code></pre>