Upload
others
View
7
Download
0
Embed Size (px)
Citation preview
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
1
Common Reference for docomo Developer support APIs
Version 2.0.0
March 17, 2014
NTT DOCOMO, Inc.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
2
Company names, product names and service names mentioned in this document are trademarks or
registered trademarks of corresponding companies.
In this document, copy rights, trademarks and registered trademarks are not specifically indicated.
Revision history
Date Version Revisions
Nov. 11, 2013 1.0.0 First version
March 17, 2014 2.0.0 Added descriptions for the cases where APIs that require user’s
authorization are used.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
3
Contents
1 Introduction....................................................................................................................................1
1.1. About this document ............................................................................................................ 4
2. To use the APIs ............................................................................................................................. 4
2.1. Outline .................................................................................................................................. 4
2.2. To create applications ........................................................................................................... 4
2.2.1. API key ........................................................................................................................ 5
2.2.2. client_id 【Needed when using APIs that require user’s authorization】 ...................... 5
2.2.3. client_secret 【Needed when using APIs that require user’s authorization】................ 5
2.3. To use APIs that require user’s authorization ....................................................................... 6
2.3.1. Outline ......................................................................................................................... 6
2.3.2. Sequence of new acquisition of access tokens ............................................................. 6
2.3.3. Sequence of access token reissuance (Refresh) ........................................................... 7
2.3.4. Setup for usage ............................................................................................................. 7
2.3.5. Notes ............................................................................................................................ 8
3. Authorization end point ................................................................................................................ 8
3.1. Request ................................................................................................................................. 8
3.2. Response (Normal case) ..................................................................................................... 10
3.3. Response (Error case) ........................................................................................................ 10
4. Token end point ........................................................................................................................... 12
4.1. Request ............................................................................................................................... 12
4.2. Response (Normal case) .................................................................................................. 15
4.3. Response (at the time of an error) ...................................................................................... 18
5. Get User ID ................................................................................................................................. 20
5.1. Request ............................................................................................................................... 20
5.2. Response (at a normal time) ............................................................................................... 21
5.3. Response (at the time of an error) ...................................................................................... 23
6. Common References for APIs..................................................................................................... 26
6.1. Request ............................................................................................................................... 26
6.2. Response ............................................................................................................................ 27
6.3. Common Error Codes ........................................................................................................ 28
(Appendix 1) List of scopes ................................................................................................................ 32
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
4
1 Introduction
1.1. About this document
This document describes how to use API keys and access tokens needed for using the APIs
provided by docomo Developer support, and corresponding requests and responses. See the
reference per function for details of each API.
Services and programs that use each API must comply with the use policy and guideline
separately specified.
The environment and mechanism to execute APIs is configured based on Authorization Code
Grant of OAuth 2.0 Authorization Framework. See RFC 6749 and RFC6750 of OAuth 2.0 for
details.
2. To use the APIs
2.1. Outline
In order for programs created by developers (hereafter, clients) to use each API provided by
docomo Developer support, API usage application must be made and API keys, client_id &
client_secret(depends on the API chosen) must be obtained. Details of each item are described
below.
2.2. To create applications
The following information is needed for API usage application. Among them, Callback URL(※)
is the end point to receive authorization codes to use APIs that require user’s authorization(See
Section 2.3) (See Subsection 2.3.2). Because Callback URL is a mandatory item, in case only the
APIs not requiring user authorization are used, dummy values (https://dummy) must be entered.
See API Common Guideline for details of other items.
<Items that must be registered in docomo Developer support>
Application name
Outline of application
Planned service start date
Service icon image
Application type
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
5
Callback URL※
Support mail address
Site URL
Further, with the API usage application, the following information can be obtained. Among them,
client_id and client_secret(※) are needed to use APIs that require user’s authorization(See Section
2.3).
<Items that must be obtained from docomo Developer support>
API key
client_id※
client_secret※
Details of each item are described below.
2.2.1. API key
API keys are an information element that must be added to requests to execute APIs and can be
obtained through usage application of docomo Developer support. Please see to it that API keys are
not referenced by outsiders.
Please make sure not to add API keys to requests for the API call for Photo Collection, Data
Storage Box and DOCOMO Phonebook. See the reference per function for each API.
2.2.2. client_id【Needed when using APIs that require user’s authorization】
An ID needed to obtain an authorization code (authorization_code) and can be obtained through
usage application of docomo Developer support.
2.2.3. client_secret 【 Needed when using APIs that require user’s
authorization】
This can be obtained by applying via docomo Developer support’s “Apply for API
Usage” .Access tokens can be obtained with authorization code and client_secret. Please see to it
that client_secret is not referenced by outsiders.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
6
2.3. To use APIs that require user’s authorization
2.3.1. Outline
In order for programs created by developers (hereafter, clients) to execute APIs that require
user’s authorization among the APIs provided by docomo Developer support, the user’s
authorization must be obtained to the effect that the clients will access the user’s resources via the
APIs and that what and how such resources are referenced and operated.
The mechanism to authenticate users and request authorization is prepared by docomo Developer
support and clients can use it. When authorization is obtained from users, the clients can obtain
access tokens from the docomo Developer support system.
In order to execute APIs that require user’s authorization, access tokens must be added to requests
in addition to API keys※
. The docomo Developer support system examines validity of the added
access tokens, and when they are judged valid, it will execute the requests specified by the clients.
(※)Please make sure not to add API keys to requests for APIs for Photo Collection, Data Storage
Box and DOCOMO Phonebook. See the reference per function for each API.
2.3.2. Sequence of new acquisition of access tokens
The following is the sequence for new acquisition of access tokens. The following 2 points require
applications to implement calling of the authentication authorization server:
・Call the authorization end point
・Call the token end point
When the authorization end point is called by using a Callback URL specified at new application
registration, scope and issued client_id as parameters, the docomoID input screen (in case docomo
ID has not been authenticated) and authorization screen are returned. When the user executes
authorization from the screen, the embedded agreement result reception end point calling process is
executed and a Callback URL already registered in docomo Developer support is called. When the
Callback URL is called, an authorization code is given as a request parameter, therefore, by calling
the token end point by using the authorization code, client_id and client_secret, an access token and
refresh token can be obtained.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
7
2.3.3. Sequence of access token reissuance (Refresh)
By calling the token end point by using the refresh token issued at new acquisition, a new access
token can be obtained.
2.3.4. Setup for usage
Photo Collection API, Data Storage Box API, docomo Phonebook API requires processing of start
of cloud usage in advance. Refer to each of the API’s notes for more details.
Apps Authentication
authorization server
Browser Apps (Callback URL) Authentication
authorization server
1. Call the authorization end point
2. If not authenticated yet, docomoID input screen is returned
3. Authenticates docmoID from docomoID input screen
4. Returns the authorization screen
5. User presses authorization button on the authorization screen
6. Returns an authentication code to destination of redirect
7. Redirect
8. Call the token end point
9. Returns a token
1. Call token end point
2. Returns a token
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
8
2.3.5. Notes
In the OAuth 2.0 specification, the client_id and authorization codes are allowed to be referenced
by third parties. However, the Authorization Code Grant supported by the docomo Developer
support system does not assume reference of access tokens and client_secret by third parties. If
access tokens are leaked, third parties can pretend as developers and execute the APIs. Further, if
client_id and client_secret are leaked, issuance of access tokens becomes possible, therefore likewise,
third parties can pretend as developers and execute the APIs. For these reasons, please see to it that
access tokens and client_secret are not referenced by third parties.
As for security, please take measures specified in the RFC of OAuth 2.0 specification.
3. Authorization end point
This chapter explains requests and responses regarding access token acquisition in case AP
Is that require user’s authorization are used.
The end point is the authorization end point in the OAuth2.0 specification and accepts aut
horization requests. Please use a browser to access the authorization end point.
Although several response_type are specified in the authorization end point in the OAuth2.
0 specification, the only response_type supported by the system is ‘code’.
3.1. Request
URL https://api.smt.docomo.ne.jp/cgi11d/authorization
HTTP method GET
Query parameter
name
response_type
Description Request type
Mandatory/Optional: Mandatory
Value Fixed to “code”
Query parameter
name
client_id
Description Client ID
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
9
Mandatory/Optional: Mandatory
Value Set client_id issued at new application registration
Query parameter
name
redirect_uri
Description Callback URI. URI to which authorization code is notified.
Mandatory/Optional: Mandatory
Value Sets Callback URL specified at new application registration
Query parameter
name
Scope
Description Scopes(English name) corresponding to the ‘API functions to be used’
requested at API usage application.
Multiple scopes can be specified by delimiting with single-byte spaces.
Mandatory/Optional: Mandatory
Value Sets scope names by delimiting with single-byte spaces. ※1
※1 A list of scopes that can be specified is shown in 0.
Query parameter
name
State
Description Specifies parameters to be provided to Callback URL. See RFC of OAuth2.0
for details..
Mandatory/Optional: Optional
Value Character strings of 1~16 characters.
The following is a sample of requests.
GET
/cgi11d/authorization?response_type=code&client_id=w2fi67u8Uk39ETeREkcXgVlMV3GsMcS54
2fdWGp6iAst&redirect_uri=https%3A%2F%2Ftest.com%2Foauth-client%2Fjsp%2Fbackcode.jsp&
scope=name+sex+tel&state=4iU
HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: api.smt.docomo.ne.jp
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
10
3.2. Response (Normal case)
A screen is returned as a response in normal cases.
3.3. Response (Error case)
The following is the response specification in case of error.
No Item Content Remarks
1 Status code 302 ※1
2 Content-Type
of Body
-(No Body)
3 Character code
of Body
-(No Body)
4 URL of
Location header
URL specified with redirectURI when
making a request to the authorization end
point
5 Content-Length
of Body
-(No Body)
※1 In the following cases, an error screen is returned with the status code 200.
+ When invalid client_id is specified
+ When specified redirect_uri does not match that registered in advance
+ When redirect_uri is not specified
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
11
Table Response parameter
No Item
name
Parameter
type
Parameter
name
Mand
atory
Forma
t
String
length
Usable
characte
r type
Remarks
1 Error
code
Query
string in
Location
header
URL
Error ○ String - - See ‘Table
List of error
codes’ for
details.
2 State Query
string in
Location
header
URL
State - String 1~16 %x20-7
E
State value
specified
when
making a
request.
Table List of error codes
No Error code Meaning Remarks
1 invalid_request Missing required parameters, invalid
parameters, a client secret effective period is
set and the client secret has expired, etc.
2 unsupported_respo
nse_type
Unsupported response_type.
3 invalid_scope Invalid scope value as below:
・scope values are empty (Only single-byte
space is specified)
・The same scope values are specified multiple
times
・Undefined scope values are specified
・scope values not permitted in the requesting
client are specified.
4 server_error Unexpected authorization server error,
5 temporarily_unava
ilable
State where the authorization server cannot be
used temporally.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
12
The following is a sample of responses.
HTTP/1.1 302 Moved Temporarily
Location: https://test.com/oauth-client/jsp/backcode.jsp?error=invalid_request
4. Token end point
This chapter explains requests and responses regarding refresh token acquisition for access
token and access token reissuance (Refresh) in case APIs that require user’s authorization a
re used.
The end point is the token end point in the OAuth2.0 specification and accepts issuance r
equests of access tokens.
Although the access token acquisition method with several grant_type is specified in the
OAuth2.0 specification, the only grant_type supported by the system are ‘authorization_code’
and ‘refresh_token’.
In case of acquisition of a new access token, the grant_type of ‘authorization_code’, and i
n case of reissuance of expired access tokens, the grant_type of ‘refresh_token’ is used. See
corresponding section for details of the Interface.
4.1. Request
URL https://api.smt.docomo.ne.jp/cgi12/token
HTTP method POST
Body の
Content-Type
application/x-www-form-urlencoded;charset=UTF-8
Character code of
Body
UTF-8
Content-Length of
Body
Size of entity body
The following is the request parameter at new acquisition of access tokens.
HTTP header
name
Authorization
Description Basic authentication credential
Mandatory/Optional: Mandatory
Value As the basic authentication scheme, URL encode a client ID and secret
individually, link them with a ‘:’ (Colon), encode with Base64 and specify.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
13
Query parameter
name
grant_type
Description Grant type
Mandatory/Optional: Mandatory
Value Fixed to “authorization_code”
Query parameter
name
Code
Description Authorization code
Mandatory/Optional: Mandatory
Value Specifies issued authorization codes.
Query parameter
name
redirect_uri
Description Callback URL
Mandatory/Optional: Mandatory
Value Set the URI specified at the authorization end point
The following is a request sample at new acquisition of access tokens.
POST /cgi12/token HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: api.smt.docomo.ne.jp
Authorization: Basic ZGowemFpWnBQWEZTY1dVd1NHSlJhazFyVk・・・zM2MxZA==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: xxx
grant_type=authorization_code&code=S542fdWGpgVl6iAstw2ETfi67ueREkcMV3GsMc8Uk39X&
redirect_uri=https://test.com/oauth-client/jsp/backcode.jsp
The following is the request parameters at access token reissuance (Refresh).
HTTP header
name
Authorization
Description Basic authentication credential
Mandatory/Optional: Mandatory
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
14
Value As the basic authentication scheme, URL encode a client ID and secret
individually, link them with a ‘:’ (Colon), encode with Base64 and specify.
Query parameter
name
grant_type
Description Grant type
Mandatory/Optional: Mandatory
Value Fixed to “refresh_token”
Query parameter
name
refresh_token
Description Refresh token
Mandatory/Optional: Mandatory
Value Specifies issued refresh token
Query parameter
name
Scope
Description Specifies scopes corresponding to access token issuance.
Multiple scopes can be specified by delimiting with single-byte spaces.
For an access token before expiration, a scope can be selected and specified
among the scopes permitted by the user. (Scopes cannot be newly added).
If a scope is not specified, an access token with the same scope will be
reissued.
Mandatory/Optional: Optional
Value Sets scope names by delimiting with single-byte spaces.
The following is a sample of request at access token reissuance (Refresh).
POST /cgi12/token HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: api.smt.docomo.ne.jp
Authorization: Basic ZGowemFpWnBQWEZTY1dVd1NHSlJhazFyVk・・・zM2MxZA==
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: xxx
grant_type=refresh_token&refresh_token=p6k3idtlwheeTtFpr6d2cT3RcRIMePmfOjZbmQnRZRrh
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
15
4.2. Response (Normal case)
The following is the response specification in normal cases.
No Item Content Remarks
1 Status code 200
2 Content-Type
of Body
application/json;charset=UTF-8
3 Character code
of Body
UTF-8
4 Cache-Control
header
no-store
5 Pragma header no-cache
6 Content-Length
of Body
Size of entity body
Table Response parameter (At new acquisition of access token)
No Item
name
Paramete
r
type
Parameter
name
Ma
nd
ato
ry
Forma
t
Char
acter
lengt
h
Usable
character
type
Remarks
1 Acces
s
token
Body
(JSON)
access_token ○ String 44 %x20-7E Access token.
Used when
accessing APIs.
2 Token
type
Body
(JSON)
token_type ○ String - - Value is fixed
to ”Bearer”
3 Effecti
ve
period
Body
(JSON)
expires_in ○ String - %x30-39 Seconds
indicating the
effective period
of access
tokens.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
16
No Item
name
Paramete
r
type
Parameter
name
Ma
nd
ato
ry
Forma
t
Char
acter
lengt
h
Usable
character
type
Remarks
4 Refres
h
token
Body
(JSON)
refresh_toke
n
- String 44 %x20-7E Refresh token.
Used at
reissuance
(Refresh) of
access tokens.
5 scope Body
(JSON)
scope ○ String 1~
512
Each
scope
value is
%x41-5A
/%x61-7
A
%x30-39
Authorized
scope.
The following is a sample at new acquisition of access tokens.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Content-Length: xxx
{
"access_token":"Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh",
"token_type":"Bearer",
"expires_in":"3600",
"refresh_token":"2ES542fdWGpgVl6iAstwTGsMc8Uk39Xfi67ueREkcMV3",
"scope":"name sex tel"
}
Table Response parameter (At access token reissuance (refresh))
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
17
No Item
name
Parameter
type Parameter
name
Ma
nd
ato
ry
Forma
t
Char
acter
lengt
h
Usable
character
type
Remarks
1 Access
token
Body
(JSON)
access_tok
en
○ String 44 %x20-7E Access token.
Used when
accessing APIs.
2 Token
type
Body
(JSON)
token_type ○ String - - Value is fixed
to ”Bearer”
3 Effecti
ve
period
Body
(JSON)
expires_in ○ String - %x30-39 Seconds
indicating the
effective period
of access
tokens.
4 Refres
h
token
Body
(JSON)
refresh_tok
en
- String 44 %x20-7E Refresh token.
Used at
reissuance
(Refresh) of
access tokens.
5 scope Body
(JSON)
scope ○ String 1~
512
Each
scope
value
is %x41-5
A/%x61-
7A
%x30-39
Authorized
scope.
The following is a sample response at access token reissuance (refresh).
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Content-Length: xxx
{
"access_token":"Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh",
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
18
"token_type":"Bearer",
"expires_in":"3600",
"refresh_token":"2ES542fdWGpgVl6iAstwTGsMc8Uk39Xfi67ueREkcMV3",
"scope":"name sex tel"
}
4.3. Response (at the time of an error)
The following table shows the specifications of the responses returned at the time of an error
No Item Description Remarks
1 Status codes 400,401,500,503 A different status code is
used for a different error
code returned.
For details, see “Table
List of Error Codes”
2 Body’s
Content-Type
application/json;charset=UTF-8
3 Body’s
Character code
UTF-8
4 Cache-Control
header
no-store
5 Pragma header no-cache
6 Body’s
Content-Length
The size of the entity body
+
Table Response parameters
No Item
name
Paramete
r
type
Paramete
r
name
Mandator
y Type
Chara
cter
string
length
Charact
er type
accepte
d
Remarks
1 Error
code
Body
(JSON)
error Yes Strin
g
- - For details, see
“Table List of
Error Codes”
Table List of Error Codes
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
19
No Status
code
Error code Meaning Remarks
1 400 invalid_request A missing mandatory parameter,
an invalid parameter, expiry of
any effective period set for client
secret, etc.
2 401 invalid_client A request from an unregistered
client, a failed client
authentication, etc.
Sends a response
including ”WWW-Auth
enticate:Basic” in the
HTTP header.
3 400 invalid_grant An invalid authorization code or
invalid refresh token specified.
redirect_uri does not match the
one used at the time of request to
the Authorization endpoint.
4 400 unauthorized_cli
ent
A request from a client not
allowed to use grant_type
specified.
5 400 unsupported_gra
nt_type
grant_type not supported
6 400 invalid_scope An invalid scope value as shown
below.
・The scope value is null or
empty (only one-byte space is
specified)
・The same scope is specified
more than once
・An undefined scope value is
specified
・The scope value specified is not
allowed for the client who has
sent a request.
7 500 server_error An unexpected error of the
authorization server
8 503 temporarily_unav
ailable
The authorization server is
temporarily unavailable.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
20
Shown below is a sample of a response.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Content-Length: xxx
{
"error":"invalid_request"
}
5. Get User ID Interface
This chapter describes the Interface for the requests and responses associated with the endpoint,
from which the ID is obtained to uniquely identify the user based on the access token.It is possible to
use this interface to obtain the user ID only if you are a subscriber of sp-mode. Application for is a
prerequisite for using this interface. Once you have applied for the API Usage please contact us via
“Support/Contact Us” section and include the name of your App that would make use of this
interface.In addition when you call the authorization endpoint and Token endpoint please include
“userid” in the scope request parameter.
5.1. Request
URL https://api.smt.docomo.ne.jp/cgi10/userid/get
HTTP method GET
HTTP header name Authorization
Description Specifies an access token
Value Specifies an access token in the form of “Bearer + Space + <access_token>”
HTTP header name X-API-Version
Description API’s version number
The version number for the initial release shall be “1.0.”
Mandatory/Option: Mandatory
Value 1.0
Shown below is a sample of a request.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
21
GET /userid/get HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: api.smt.docomo.ne.jp
Content-Length: 0
Authorization: Bearer Fprp6k3idtlwheeTt6d2cT3RcRIMePmfOjZbmQnRZRrh
X-API-Version: 1.0
5.2. Response (at a normal time)
The following table shows the specifications of the responses returned at a normal time.
No Item Description Remarks
1 Status code 200
2 Body’s
Content-Type
application/json;charset=UTF-8
3 Body’s
Character code
UTF-8
4 Cache-Control
header
no-store
5 Pragma header no-cache
6 Body’s
Content-Length
The size of the entity body
7 WWW-Authentic
ate
Bearer+Space+realm=”userid”
8 X-API-Version API’s version number.
Up to 8 bytes (one-byte
numerical symbols and ”.”
decimal point)
The same version
number as the request
is given to the
response for the sake
of security.
Table Response parameters
No Item
name
Paramete
r
type
Parameter
Name
Ma
nd
ato
ry
Type
Chara
cter
string
length
Character type
accepted
Remar
ks
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
22
No Item
name
Paramete
r
type
Parameter
Name
Ma
nd
ato
ry
Type
Chara
cter
string
length
Character type
accepted
Remar
ks
1 Proces
sing
Result
code
Body
(JSON)
result_code Ye
s
String Fixed
4
bytes
One-byte number “2000
”Fixed
2 User
ID
Body
(JSON)
user_id - String - One-byte
alphanumeric
character
0x30~0x39,0x41
~0x5A,0x61~7A,
0x2B,0x2F,0x3D
(Base64-encoded
value)
Please ignore if any items other than those specified above are returned.
Shown below is a sample of a response.
HTTP/1.1 200 OK
Date: Wed, 19 Nov 2011 09:24:37 GMT
Content-Type: application/json;charset=UTF-8
WWW-Authenticate: Bearer realm=”userid”
X-API-Version: 1.0
{
"result_code":"2000",
"user_id":"UG4UUE/lHqTC6gx0cHnhbykKzmZlstJX1wNmvFBVzwq3RLgb0nayJVxqZ2RCy009"
}
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
23
5.3. Response (at the time of an error)
The following table shows the specifications of the responses returned at the time of an error.
No Item Description Remarks
1 Status code 400,401,403,404,405,408,500,503 A different status
code is used for a
different
processing result
code returned.
For details, see
“Table List of
Processing Result
Codes”
2 Body’s
Content-Type
application/json;charset=UTF-8
3 Body’s
Character code
UTF-8
4 Cache-Control
header
no-store
5 Pragma header no-cache
6 Body’s
Content-Length
The size of the entity body
7 WWW-Authenti
cate
Bearer+Space+realm=”userid”
In case of HTTP status errors
400,401,403,it it given based on the
processing result:
error=”【Error codes character
string】”
400:error=”invalid_request”
401:error=”invalid_token”
403:error=”insufficient_scope”
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
24
No Item Description Remarks
8 X-API-Version API’s version number
Up to 8 bytes (one-byte numerical
symbols and ”.” decimal point)
The same version
number as the
request is given to
the response.
Table Response parameters
No Item
name
Paramete
r
type
Parameter
name
Ma
nd
ato
ry
Type
Chara
cter
string
length
Charact
er type
accepte
d
Remarks
1 Proces
sing
result
code
Body
(JSON)
result_code Ye
s
String Fixed
4
bytes
One-byt
e
number
For details, see
“Table List of
Processing
Result Codes.”
Table List of Processing Result Codes
No Categ
ory Status code
Status Processing
result code
Details
1 Norma
l
system
200 Normal end 2000 Normal
2 Abnor
mal
system
400 Invalid request 4000 Invalid
parameter
(a version
number not
allowed, etc.)
3 401 Invalid
authentication status
4100 An access
token that does
not exist or
access token
no longer valid
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
25
No Categ
ory Status code
Status Processing
result code
Details
4101 The user does
not exist
(not subscribed
to sp mode)
4 403 No access right 4500 Mismatched
scopes
5 404 Request URL not
available
- -
5 405 Method not allowed - -
6 408 Timeout 3001 Temporary
congestion,
etc.
7 500 Internal processing
error
- -
8 503 Service not
available
3002 Overload
status, etc.
Shown below is a sample of a response.
HTTP/1.1 401 Unauthorized
Date: Wed, 19 Nov 2011 09:24:37 GMT
Content-Type: application/json;charset=UTF-8
WWW-Authenticate: Bearer realm=”userid”
error=”invalid_token”
X-API-Version: 1.0
{
"result_code":"4100"
}
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
26
6. Common References for APIs
This chapter describes request, responses, and common error codes.
6.1. Request
The query parameter of a request must include the APIKEY parameter in order to execute an API.
Please note that the APIs for Photo Collection, Data Storage BOX, and DOCOMO Phonebook are
not supported by the APIKEY parameter. For these APIs not supported, please see the functional
references for the respective APIs.
Query parameter
name
APIKEY
Description API key. This is a key uniquely assigned to each application.
Mandatory/Optional: Mandatory
Value Alphanumeric characters
Shown below is a sample of a GET request.
GET /knowledgeQA/v1/ask?q=人類初の宇宙飛行士は&APIKEY=<API key> HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: api.apigw.smt.docomo.ne.jp
Connection: keep-alive
Accept: application/json
User-Agent: <each client>
Accept-Encoding: gzip,deflate,sdch
The authorization header of a request must include an access token in order to execute an API
requiring user authorization.
HTTP header
name
Authorization
Description OAuth authentication Authorization header
Mandatory/Optional: Mandatory if the application uses any API requiring
authorization
Value Specifies an access token in the form of “Bearer + Space + <access_token>.”
Shown below is a sample of a POST request of an API requiring user authorization.
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
27
POST /1/contact/add?APIKEY=<APIKEY> HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/33.0.1750.117 Safari/537.36
Host: phonebook-api.smt.docomo.ne.jp
Content-Type: application/json; charset=utf-8
Content-Length: 1234
Authorization: Bearer <access_token>
{
"key" : "value"
}
6.2. Response
Shown below is a sample of a response.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Fri, 01 Nov 2013 10:13:46 GMT
Content-Length: 286
Connection: keep-alive
{
code: “S020010”,
message:
{
textForDisplay: “インターネットで調べたところ、一位は、ガガーリンです。”,
textForSpeech: “インターネットで調べたところ、一位は、ガガーリンです。”
},
answers: [
{
rank: “1”,
answerText: “ガガーリン”,
linkText: “ページ a タイトル”,
linkUrl: “http://aaa.aaa.com”
},
{
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
28
rank: “2”,
answerText: “ユーリイ・ガガーリン”,
linkText: “ページ b タイトル”,
linkUrl: “http://bbb.bbb.com”
}
]
}
6.3. Common Error Codes
This section describes the common error codes returned by the docomo Developer support system to
the all APIs, except those of Photo Collection, Data Storage BOX, and DOCOMO Phonebook,
which are not supported by these common codes. For those APIs not supported, please see the
functional references for the respective APIs.
・List of error messages
Error type Error details
/Description
Error codes
(messageId)
Error type Error output
details (text)
HTTP
Stats
Code
Reason
phrase
1 Authentic
ation/
authorizat
ion
1. A basic
authentication
error due to
an invalid
user name or
password
POLSLA008 policyExce
ption
-UNAUTHORI
ZED- Check
the
username/pass
word
401 Unautho
rized
2. An
authentication
error due to
an invalid
APIKEY
name or
APIKEY
value.
POLSAL009 policyExce
ption
Unable to
perform
ApiKey based
Authentication
401 Unautho
rized
3. An
authorization
error
POL0001 policyExce
ption
-ACCESS
DENIED-
Service not
403 Forbidd
en
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
29
associated with
ServiceGroup
2 CoS 1.An access
exceeding
maximum
throughput
allowed
POLSLA001 policyExce
ption
Access denied
for crossing the
maximum TC
messages
403 Forbidd
en
2.An access
exceeding
maximum
volume
allowed
POLSLA002 policyExce
ption
Access denied
for crossing the
maximum VC
messages
403 Forbidd
en
3.An access
to an
unusable
API
POLSLA005 policyExce
ption
Access denied
for accessibility
403 Forbidd
en
3 Southbou
nd
Throttling
1. An access
exceeding the
threshold for
the number of
requests
THRL004 policyExce
ption
Request rate
reached, Please
try after
sometime
403 Forbidd
en
4 OAuth
resource
server
1. An access
without an
access token
OAUTHE001 policyExce
ption
OAuth Access
Token is null or
empty in the
request
403 Forbidd
en
2. An access
token
invalid
error
OAUTHE002 policyExce
ption
Invalid OAuth
Access Token
in the request
403 Forbidd
en
3. An OAuth
server error
OAUTHE003 policyExce
ption
Error in getting
access token
details from
OpenAM
OAuth2.0
Authorization
server
503 Service
Unavail
able
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
30
5 Interface 1. An
endpoint
connection
error
SVCEXCP50
3
policyExce
ption
A error
message is
issued
according to
the error
pattern of an
EndPoint
connection
error.
503 Service
Unavail
able
2. An invalid
request
message
SVCEXCP40
0
policyExce
ption
String index
out of range: -1
400 Bad
Request
*1 In case of a Reset response in connecting to the endpoint (Connection Refuse): Connection
refused
In case of a failed connection to the endpoint (Connection not open): No route to host
In case of no response after connected to the endpoint (Response timeout): Read timed out
In case of a forced disconnection after connected to the endpoint (Response close):
Connection reset, etc.
・Error response message format
ResponsesContent-Type application/json; charset=ISO-8859-1
・Error response parameters
No. Parameter Description Mandatory Type
1 requestError Error response Yes Object
2 requestError/policyException Response
information
Yes Object
3 requestError/policyException@messageId Error code Yes String
4 requestError/policyException@text Error details Yes String
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
31
・A sample of an error response
{
"requestError":{
"policyException":{
"messageId":"POLSLA008",
"text":"Unable to perform ApiKey based Authentication"
}
}
}
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
32
(Appendix 1) List of scopes
This appendix shows the values that can be set in the scope parameter of the authorization endpoint
described in 3.1. For the scope parameter, please specify a value of “scope (English name)” in the
table below.
API name scope(Japanese name) scope(English name)
Photo
Collection
写 真 ・ 動 画 リ ス ト の 取 得
(acquisition of photo/video lists)
PhotoGetContentsList
写真・動画の取得 (acquisition of
photo/video)
PhotoGetContent
写 真 ・ 動 画 の ア ッ プ ロ ー ド
(upload of photo/video)
PhotoUploadContent
クラウド空き容量の確認 (check
the available size of the cloud)
PhotoGetVacantSize
グ ル ー プ 情 報 の 取 得
(acquisition of group information)
PhotoGetGroupInfo
グループ情報の編集 (editing of
group information)
PhotoUpdateGroupInfo
回転情報の変更 (update of
rotate information)
PhotoUpdateRotateInfo
ごみ箱情報の編集 (editing of
trash information)
PhotoUpdateTrashInfo
「 友人の写真 」情報の取得
(acquisition of “friend’s photo”
information)
PhotoGetFriendsPhotoInfo
DOCOMO
Phonebook
マイプロフィールの利用 (use of
My Profile)
PhonebookAccessProfile
連絡先の利用 (use of a contact) PhonebookAccessContact
連絡先の追加 (addition of a
contact)
PhonebookAddContact
友達のタイムラインへ情報を配
信 (post information to the
timeline of a friend)
PhonebookPostFeed
つ な が り 情 報 等 を 取 得
(acquisition of
“Tsunagari(connection)”
*To be provided in future
NTT DOCOMO Confidential
Copyright © 2014 NTT DOCOMO, Inc. All Rights Reserved
33
information, etc.
Data Storage
BOX
サービス専用フォルダへのアクセ
ス (access to a special folder of
the service)
DataboxAll