Skip to content

Commit c39efcf

Browse files
author
Phrase
committed
1 parent b1c2154 commit c39efcf

File tree

1 file changed

+1
-367
lines changed

1 file changed

+1
-367
lines changed

‎README.md‎

Lines changed: 1 addition & 367 deletions
Original file line numberDiff line numberDiff line change
@@ -1,372 +1,6 @@
11
# phrase-api
2-
Phrase is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase for your account.
3-
4-
## API Endpoint
5-
6-
```
7-
https://api.phrase.com/v2/
8-
```
9-
10-
The API is only accessible via HTTPS, the base URL is <code>https://api.phrase.com/</code>, and the current version is <code>v2</code> which results in the base URL for all requests: <code>https://api.phrase.com/v2/</code>.
11-
12-
## Usage
13-
14-
[curl](http://curl.haxx.se/) is used primarily to send requests to Phrase in the examples. On most you'll find a second variant using the [Phrase API v2 client](https://phrase.com/cli/) that might be more convenient to handle. For further information check its [documentation](https://help.phrase.com/help/phrase-in-your-terminal).
15-
16-
## Use of HTTP Verbs
17-
18-
Phrase API v2 tries to use the appropriate HTTP verb for accessing each endpoint according to REST specification where possible:
19-
20-
<div class=\"table-responsive\">
21-
<table class=\"basic-table\">
22-
<thead>
23-
<tr class=\"basic-table__row basic-table__row--header\">
24-
<th class=\"basic-table__cell basic-table__cell--header\">Verb</th>
25-
<th class=\"basic-table__cell basic-table__cell--header\">Description</th>
26-
</tr>
27-
</thead>
28-
<tbody>
29-
<tr>
30-
<td class=\"basic-table__cell\">GET</td>
31-
<td class=\"basic-table__cell\">Retrieve one or multiple resources</td>
32-
</tr>
33-
<tr>
34-
<td class=\"basic-table__cell\">POST</td>
35-
<td class=\"basic-table__cell\">Create a resource</td>
36-
</tr>
37-
<tr>
38-
<td class=\"basic-table__cell\">PUT</td>
39-
<td class=\"basic-table__cell\">Update a resource</td>
40-
</tr>
41-
<tr>
42-
<td class=\"basic-table__cell\">PATCH</td>
43-
<td class=\"basic-table__cell\">Update a resource (partially)</td>
44-
</tr>
45-
<tr>
46-
<td class=\"basic-table__cell\">DELETE</td>
47-
<td class=\"basic-table__cell\">Delete a resource</td>
48-
</tr>
49-
</tbody>
50-
</table>
51-
</div>
52-
53-
54-
## Identification via User-Agent
55-
56-
You must include the User-Agent header with the name of your application or project. It might be a good idea to include some sort of contact information as well, so that we can get in touch if necessary (e.g. to warn you about Rate-Limiting or badly formed requests). Examples of excellent User-Agent headers:
57-
58-
```
59-
User-Agent: Example Mobile App (example@phrase.com)
60-
User-Agent: ACME Inc Python Client (http://example.com/contact)
61-
```
62-
63-
If you don't send this header, you will receive a response with 400 Bad Request.
64-
65-
66-
## Lists
67-
68-
When you request a list of resources, the API will typically only return an array of resources including their most important attributes. For a detailed representation of the resource you should request its detailed representation.
69-
70-
Lists are usually [paginated](#pagination).
71-
72-
73-
## Parameters
74-
75-
Many endpoints support additional parameters, e.g. for pagination. When passing them in a GET request you can send them as HTTP query string parameters:
76-
77-
```
78-
$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2\"
79-
```
80-
81-
When performing a POST, PUT, PATCH or DELETE request, we recommend sending parameters that are not already included in the URL, as JSON body:
82-
83-
```
84-
$ curl -H 'Content-Type: application/json' -d '{\"name\":\"My new project\"}' -u EMAIL_OR_ACCESS_TOKEN https://api.phrase.com/v2/projects
85-
```
86-
87-
Encoding parameters as JSON means better support for types (boolean, integer) and usually better readability. Don't forget to set the correct Content-Type for your request.
88-
89-
*The Content-Type header is omitted in some of the following examples for better readbility.*
90-
91-
92-
## Errors
93-
94-
95-
### Request Errors
96-
97-
If a request contains invalid JSON or is missing a required parameter (besides resource attributes), the status `400 Bad Request` is returned:
98-
99-
```
100-
{
101-
\"message\": \"JSON could not be parsed\"
102-
}
103-
```
104-
105-
106-
### Validation Errors
107-
108-
When the validation for a resource fails, the status `422 Unprocessable Entity` is returned, along with information on the affected fields:
109-
110-
```
111-
{
112-
\"message\": \"Validation Failed\",
113-
\"errors\": [
114-
{
115-
\"resource\": \"Project\",
116-
\"field\": \"name\",
117-
\"message\": \"can't be blank\"
118-
}
119-
]
120-
}
121-
```
122-
123-
124-
## Date Format
125-
126-
Times and dates are returned and expected in [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date format:
127-
128-
```
129-
YYYY-MM-DDTHH:MM:SSZ
130-
```
131-
132-
Instead of 'Z' for UTC time zone you can specify your time zone's locale offset using the following notation:
133-
134-
```
135-
YYYY-MM-DDTHH:MM:SS±hh:mm
136-
```
137-
138-
Example for CET (1 hour behind UTC):
139-
140-
```
141-
2015-03-31T13:00+01:00
142-
```
143-
144-
Please note that in HTTP headers, we will use the appropriate recommended date formats instead of ISO 8601.
145-
146-
147-
## Authentication
148-
149-
<div class=\"alert alert-info\">For more detailed information on authentication, check out the <a href=\"#authentication\">API v2 Authentication Guide</a>.</div>
150-
151-
There are two different ways to authenticate when performing API requests:
152-
153-
* E-Mail and password
154-
* Oauth Access Token
155-
156-
157-
### E-Mail and password
158-
159-
To get started easily, you can use HTTP Basic authentication with your email and password:
160-
161-
```
162-
$ curl -u username:password \"https://api.phrase.com/v2/projects\"
163-
```
164-
165-
166-
### OAuth via Access Tokens
167-
168-
You can create and manage access tokens in your [profile settings](https://app.phrase.com/settings/oauth_access_tokens) in Translation Center or via the [Authorizations API](#authorizations).
169-
170-
Simply pass the access token as the username of your request:
171-
172-
```
173-
$ curl -u ACCESS_TOKEN: \"https://api.phrase.com/v2/projects\"
174-
```
175-
176-
or send the access token via the `Authorization` header field:
177-
178-
```
179-
$ curl -H \"Authorization: token ACCESS_TOKEN\" https://api.phrase.com/v2/projects
180-
```
181-
182-
For more detailed information on authentication, check out the <a href=\"#authentication\">API v2 Authentication Guide</a>.
183-
184-
#### Send via parameter
185-
186-
As JSONP (and other) requests cannot send HTTP Basic Auth credentials, a special query parameter `access_token` can be used:
187-
188-
```
189-
curl \"https://api.phrase.com/v2/projects?access_token=ACCESS_TOKEN\"
190-
```
191-
192-
You should only use this transport method if sending the authentication via header or Basic authentication is not possible.
193-
194-
### Two-Factor-Authentication
195-
196-
Users with Two-Factor-Authentication enabled have to send a valid token along their request with certain authentication methods (such as Basic authentication). The necessity of a Two-Factor-Authentication token is indicated by the `X-PhraseApp-OTP: required; :MFA-type` header in the response. The `:MFA-type`field indicates the source of the token, e.g. `app` (refers to your Authenticator application):
197-
198-
```
199-
X-PhraseApp-OTP: required; app
200-
```
201-
202-
To provide a Two-Factor-Authentication token you can simply send it in the header of the request:
203-
204-
```
205-
curl -H \"X-PhraseApp-OTP: MFA-TOKEN\" -u EMAIL https://api.phrase.com/v2/projects
206-
```
207-
208-
Since Two-Factor-Authentication tokens usually expire quickly, we recommend using an alternative authentication method such as OAuth access tokens.
209-
210-
### Multiple Accounts
211-
212-
Some endpoints require the account ID to be specified if the authenticated user is a member of multiple accounts. You can find the eight-digit account ID inside <a href=\"https://app.phrase.com/\" target=\"_blank\">Translation Center</a> by switching to the desired account and then visiting the account details page. If required, you can specify the account just like a normal parameter within the request.
213-
214-
## Pagination
215-
216-
Endpoints that return a list or resources will usually return paginated results and include 25 items by default. To access further pages, use the `page` parameter:
217-
218-
```
219-
$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2\"
220-
```
221-
222-
Some endpoints also allow a custom page size by using the `per_page` parameter:
223-
224-
```
225-
$ curl -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects?page=2&per_page=50\"
226-
```
227-
228-
Unless specified otherwise in the description of the respective endpoint, `per_page` allows you to specify a page size up to 100 items.
229-
230-
231-
## Link-Headers
232-
233-
We provide you with pagination URLs in the [Link Header field](http://tools.ietf.org/html/rfc5988). Make use of this information to avoid building pagination URLs yourself.
234-
235-
```
236-
Link: <https://api.phrase.com/v2/projects?page=1>; rel=\"first\", <https://api.phrase.com/v2/projects?page=3>; rel=\"prev\", <https://api.phrase.com/v2/projects?page=5>; rel=\"next\", <https://api.phrase.com/v2/projects?page=9>; rel=\"last\"
237-
```
238-
239-
Possible `rel` values are:
240-
241-
<div class=\"table-responsive\">
242-
<table class=\"basic-table\">
243-
<thead>
244-
<tr class=\"basic-table__row basic-table__row--header\">
245-
<th class=\"basic-table__cell basic-table__cell--header\">Value</th>
246-
<th class=\"basic-table__cell basic-table__cell--header\">Description</th>
247-
</tr>
248-
</thead>
249-
<tbody>
250-
<tr>
251-
<td class=\"basic-table__cell\">next</td>
252-
<td class=\"basic-table__cell\">URL of the next page of results</td>
253-
</tr>
254-
<tr>
255-
<td class=\"basic-table__cell\">last</td>
256-
<td class=\"basic-table__cell\">URL of the last page of results</td>
257-
</tr>
258-
<tr>
259-
<td class=\"basic-table__cell\">first</td>
260-
<td class=\"basic-table__cell\">URL of the first page of results</td>
261-
</tr>
262-
<tr>
263-
<td class=\"basic-table__cell\">prev</td>
264-
<td class=\"basic-table__cell\">URL of the previous page of results</td>
265-
</tr>
266-
</tbody>
267-
</table>
268-
</div>
269-
270-
## Rate Limiting
271-
272-
All API endpoints are subject to rate limiting to ensure good performance for all customers. The rate limit is calculated per user:
273-
274-
* 1000 requests per 5 minutes
275-
* 4 concurrent (parallel) requests
276-
277-
For your convenience we send information on the current rate limit within the response headers:
278-
279-
<div class=\"table-responsive\">
280-
<table class=\"basic-table\">
281-
<thead>
282-
<tr class=\"basic-table__row basic-table__row--header\">
283-
<th class=\"basic-table__cell basic-table__cell--header\">Header</th>
284-
<th class=\"basic-table__cell basic-table__cell--header\">Description</th>
285-
</tr>
286-
</thead>
287-
<tbody>
288-
<tr>
289-
<td class=\"basic-table__cell\" style=\"white-space: nowrap;\"><code>X-Rate-Limit-Limit</code></td>
290-
<td class=\"basic-table__cell\">Number of max requests allowed in the current time period</td>
291-
</tr>
292-
<tr>
293-
<td class=\"basic-table__cell\" style=\"white-space: nowrap;\"><code>X-Rate-Limit-Remaining</code></td>
294-
<td class=\"basic-table__cell\">Number of remaining requests in the current time period</td>
295-
</tr>
296-
<tr>
297-
<td class=\"basic-table__cell\" style=\"white-space: nowrap;\"><code>X-Rate-Limit-Reset</code></td>
298-
<td class=\"basic-table__cell\">Timestamp of end of current time period as UNIX timestamp</td>
299-
</tr>
300-
</tbody>
301-
</table>
302-
</div>
303-
304-
If you should run into the rate limit, you will receive the HTTP status code `429: Too many requests`.
305-
306-
If you should need higher rate limits, [contact us](https://phrase.com/contact).
307-
308-
309-
## Conditional GET requests / HTTP Caching
310-
311-
<div class=\"alert alert-info\"><p><strong>Note:</strong> Conditional GET requests are currently only supported for <a href=\"#locales_download\">locales#download</a> and <a href=\"#translations_index\">translations#index</a></p></div>
312-
313-
We will return an ETag or Last-Modified header with most GET requests. When you request a resource we recommend to store this value and submit them on subsequent requests as `If-Modified-Since` and `If-None-Match` headers. If the resource has not changed in the meantime, we will return the status `304 Not Modified` instead of rendering and returning the resource again. In most cases this is less time-consuming and makes your application/integration faster.
314-
315-
Please note that all conditional requests that return a response with status 304 don't count against your rate limits.
316-
317-
```
318-
$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\"
319-
HTTP/1.1 200 OK
320-
ETag: \"abcd1234abcdefefabcd1234efab1234\"
321-
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
322-
Status: 200 OK
323-
324-
$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\" -H 'If-None-Match: \"abcd1234abcdefefabcd1234efab1234\"'
325-
HTTP/1.1 304 Not Modified
326-
ETag: \"abcd1234abcdefefabcd1234efab1234\"
327-
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
328-
Status: 304 Not Modified
329-
330-
$ curl -i -u EMAIL_OR_ACCESS_TOKEN \"https://api.phrase.com/v2/projects/1234abcd1234abcdefefabcd1234efab/locales/en/download\" -H \"If-Modified-Since: Wed, 28 Jan 2015 15:31:30 UTC\"
331-
HTTP/1.1 304 Not Modified
332-
Last-Modified: Wed, 28 Jan 2015 15:31:30 UTC
333-
Status: 304 Not Modified
334-
```
335-
336-
337-
## JSONP
338-
339-
The Phrase API supports [JSONP](http://en.wikipedia.org/wiki/JSONP) for all GET requests in order to deal with cross-domain request issues. Just send a `?callback` parameter along with the request to specify the Javascript function name to be called with the response content:
340-
341-
```
342-
$ curl \"https://api.phrase.com/v2/projects?callback=myFunction\"
343-
```
344-
345-
The response will include the normal output for that endpoint, along with a `meta` section including header data:
346-
347-
```
348-
myFunction({
349-
{
350-
\"meta\": {
351-
\"status\": 200,
352-
...
353-
},
354-
\"data\": [
355-
{
356-
\"id\": \"1234abcd1234abc1234abcd1234abc\"
357-
...
358-
}
359-
]
360-
}
361-
});
362-
```
363-
364-
To authenticate a JSONP request, you can send a valid [access token](#authentication) as the `?access_token` parameter along the request:
365-
366-
```
367-
$ curl \"https://api.phrase.com/v2/projects?callback=myFunction&access_token=ACCESS-TOKEN\"
368-
```
3692

3+
Phrase is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase for your account.
3704

3715
This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
3726

0 commit comments

Comments
 (0)