DRS_RESTful_APIx - Sicap

flashypumpkincenterΛογισμικό & κατασκευή λογ/κού

14 Δεκ 2013 (πριν από 4 χρόνια και 18 μέρες)

148 εμφανίσεις









sicap
/
DEVICE RESOURCE SERV
ER


DRS

-

RESTFUL API




DRS

1.0

DOCUMENT VERSION
1.3

DOCUMENT STATUS
FINAL







DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland


Phone:

Fax:

E
-
Mail:


+41 (0) 31 978 90 90

+41 (0) 31 978 90 99

info@sicap.com











Business confidential


This document is intended for Sicap’s internal use or for persons having signed an NDA with Sicap. It
contains confidential information and any person accessing it must comply to the confidentiality
obligations adherent to the dist
ribution of this document.

Sicap does not take over any responsibility or liability or grant warranties of any kind regarding this
document or the information in it.

This document and the solution it describes are protected by copyright according to appli
cable laws.
The information in this document is subject to change without notice.

Copyright © Sicap
AG
20
10
. All rights reserved





DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

3
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


Checklist of changes

Version

Date

Changed by

Comments / nature of the change

1.0

05
/0
7
/201
2

Florian PROCH

Initial draft version.

1.1

10/07/2012

Florian PROCH

Updated after review

1.2

24
/07/2012

Florian PROCH

Updated after
second
review

1.3

26/07/2012

Florian PROCH

Updated with new method


Released versions

Version

Date

Released by

Comments











DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

4
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


Table of content

Checklist of changes

................................
................................
................................
...............................

3

Released versions

................................
................................
................................
................................
....

3

1.

Introduct
ion

................................
................................
................................
................................
........

5

1.1

Summary and scope of the document

................................
................................
..............................

5

1.2

Target Readership

................................
................................
................................
.............................

5

1.3

Requ
irements of the reader

................................
................................
................................
...............

5

2

Overview

................................
................................
................................
................................
..............

6

3

Available API(s)
................................
................................
................................
................................
...

7

3.1

Admin
API

................................
................................
................................
................................
..........

7

3.1.1

loadDRB()

................................
................................
................................
................................
.......

7

3.2

Common API

................................
................................
................................
................................
.....

8

3.2.1

getRealm
s()

................................
................................
................................
................................
....

8

3.2.2

getBrands(String realm)

................................
................................
................................
.................

8

3.2.3

getBrands(String realm, String filter, String type)

................................
................................
..........

9

3.2.4

getModels(String realm, String brand)

................................
................................
.........................

10

3.2.5

getModels(String realm, String brand, String filter, String type)

................................
..................

11

3.2.6

resolveModel(String realm, Strin
g[] imeis, String[] modelIds, String[] profileURLs)

....................

12

3.3

Characteristics API

................................
................................
................................
..........................

14

3.3.1

getCharacteristicsFromIMEI(String realm, String characteristicType, String[] imeis, String[]
filters)

14

3.3.2

getCharacteristicsFromProfileIURL(String realm, String characteristicType, String[] profileUrls,
String[] filters)

................................
................................
................................
................................
...........

16

3.3.3

getCharacteristicsFromModelId(String realm, String characteristicType, String[] modelIds,
String[] filters)

................................
................................
................................
................................
...........

18

3.3.4

getCharacteristicsFromRealmBrandModel (String realm, String brand, String model, String
characteristictype, String[] filters)

................................
................................
................................
.............

20

3.3.5

getCharacteristics (String[] types)

................................
................................
................................

21

4

Annexe

................................
................................
................................
................................
...............

23

4.1

Error code & message

................................
................................
................................
.....................

23

4.2

Terms & Definition

................................
................................
................................
...........................

24

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

5
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


1.


Introduction

Current document describes usage of the
DRB

Server RESTful API
.

1.1

Summary

and scope

of the document

This document is applicable from
DRB Server

1.0.

1.2

Target Readership

This document is written for the following readership:

-

Sicap Front Office Provider

-

Sicap Back Office Provider

-

Sicap Test Management Group

-

External Application Development Teams

1.3

Requirements

of the reader

Base knowledge of
DRB Server

is requi
red
.


DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

6
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


2

Ov
erview


The interface permits to
perform

some
REST API calls

on
DRB Server platform and obtain
JSON
Objects

containing all information about the devices that the DRB is aware of
.


The format of t
he JSON

Object (class JSONResponse) is
:

{


“ok ” : true,

“error
Code
” : “
XX451YT
”,

“error” : “Ooops, I did it again”,

“result” : {





[...]

}

}


Name

Description

Values

ok

Result status of the API

true/false

errorCode

Error code
. Not present when ok is
“true”


敲e潲

A獳s捩慴敤e敲e潲om敳獡se
. Not present when ok is “true”


r敳畬t

o敳畬t of t桥h捡ll





All Amf猠rof 扥bi湳nwit栠t桥hAmf 湡m攠慮搠t桥hAmf v敲獩e渮

In the rest of the document “http(S)://server:port/component_context/” will be shortcut

to “/restapi/”
.


All parameter values are case insensitive (in URL and HTTP parameters).

All request parameters are present in responses (parameter names AND values

coming from DRB if
possible
; e.g: if it was requested “nokia”, in responses we’ll have “No
kia”
)
.


When a request
can
return

multiple
values (for
example
resolveModel
)

but

not values are found, an
empty list will be returned.



When a request accept multiple parameter values (resolvedModel?IMEI=12345&IMEI=54321)

but one
parameter cause an error, a couple error / errorCode is defined inside the result for each parameter
involved.


All attributes are mandatory, except if specified as optional.


DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

7
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3

Available API(s)

3.1

Admin
API

3.1.1

loadDRB
()


Synopsis:

Allow t
o
load
information about devices from a DRB.


Description
:

API short name

admin

API version

1_0

Method

GET

Base URL

/restapi/
admin
/{version}/
loadDRB

Parameter(s)



file
p
慴h

: 潰oi潮慬
. R敬慴iv攠P慴栠t漠t桥hDRB fil攠from t桥h獥牶敲e
fil敳e獴em

(URI 獣sem攠
form慴)
. If 湯n 灲敳p湴, 灡p栠will 扥blo慤a搠
from 愠捯湦ig畲慴io渠fil攮

Result

Resu
lt will be return
ed

after filepath validation
, before having the status of
the DRB import
.
To know the status of the DRB import, you must check in
logs
.

The file is validated if
it
is a
valid tar

file
and contains
all mandatory

CSV files in function to the DRS configuration.



fil数慴栠: 潰oi潮慬. R敬慴iv攠P慴栠t漠t桥hDRB fil攠from t桥h獥牶敲e
fil敳e獴em

Errors

If filepath

is not valid, a specific error will be returned

(errorCode 10)

If file not found, a specific error will be returned (errorCode 12)

If the file designed by filepath in not a DRB valid file, a specific error will be
returned

(errorCode 13)

If DRB load is pe
nding, a specific error will be returned (errorCode 14)

Request example

/restapi/

admin

/1_0/

loadDRB
?filePath=
file://hostname/path/drb1.0.tar

Response example

{




file
p
慴h
”:


fil攺LL桯獴湡meL灡p栯摲戱d〮t慲
”,

}






DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

8
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.2

Common API

3.2.1

getRealms
()


Synopsis:

Retrieve available realms.


Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/
common
/{version}/
realms
/

Parameter(s)


Result



r敡em猺 Availa扬攠r敡ems

Request example

/restapi/
common/1_0
/
realms
/

Response example

{



“realms”: [ “generic”, “orange”, “bx28” ]

}



3.2.2

getBrands
(String realm)


Synopsis:

Retrieve brand list within a realm.


Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/
common
/{version}/
{realm}/brands
/

Parameter(s)



r敡em: t桥hr敡lm

Result



r敡em: t桥hr敡lm



扲慮摳
: t桥h扲b湤猠withi渠愠r敡em

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

9
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


Errors

If re
alm is
unknown
, a

specific error will be
returned

(errorCode 20)

Request example

/restapi/common/1_0/
generic/brands
/

Response example

{



“realm” : “generic”,

“brands”: [ “Nokia”, “HTC”, “Samsung” ]

}



3.2.3

getBrands(String realm, String filter, String type)


Synopsis:

Retrieve brand list starting

with (or containing)

a
filter

within a realm
.


Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/
common
/{version}/
{realm}/brands/{filter}

Parameter(s)



r敡em: t桥hr敡lm



filt敲e t桥hfilt敲et漠慰aly 潮ot桥h扲慮搠name



ty灥p
(
O灴i潮慬) 周攠ty灥

潦 t桥hfilt敲
. C慮ab攠≣潮"ai湳n

潮ly


If 湯n
present, the search will be done by using “startWith”

Result




r敡em: t桥hr敡lm



filt敲e t桥hfilt敲et漠慰aly 潮ot桥h扲慮搠name



ty灥p
(
O灴i潮慬) 周攠ty灥

潦 t桥hfilt敲




扲慮摳b: 周攠
扲慮d
s

獴慲ai湧

wit栠(潲o捯湴aini湧n


filt敲

wit桩渠愠
r敡em

Errors

If realm is unknown, a specific error will be
returned

(errorCode 20)

If type is not “contains”, a specific error will be returned

E敲e潲o潤攠oㄩ

Request example
s

/restapi/common/1_0/
generic/brands
/nok

/restapi/common/1_0/
generic/brands
/
oki
?type=contains

Response example
s

{



“realm” : “generic”,


filter
” : “nok”,

“brands”: [ “
N
okia” ]

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

10
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


}


{



“realm” : “generic”,


filter
” : “
oki
”,

“type” : “contains”,

“brands”: [ “
N
okia” ]

}



3.2.4

getModels(String realm, String brand)


Synopsis:

Retrieve model list for a brand within a realm
.


Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/
common
/{version}/
{realm}/
{
brand
}/models
/

Parameter(s)



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d

Result



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d



mo摥ls
: t桥h
m潤ol猠f潲o愠扲慮搠
withi渠愠r敡lm

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If brand is unknown, a specific error will be returned

(errorCode 22)

Request example

/restapi/common/1_0/
generic/
HTC/models
/

Response example

{



“realm” : “generic”,

“brand” : “HTC”,

“models”: [ “Desire”, “Hero”, “Sensation” ]

}


DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

11
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.2.5

getModels(String realm, String brand, String filter, String type)


Synopsis:

Retrieve model
list for a brand starting with (or containing) a filter

within a realm.


Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/
common
/{version}/
{realm}/{brand}/models/{filter}

Parameter(s)



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d



filt敲e t桥hfilt敲et漠慰aly 潮ot桥hmo摥l 湡me



ty灥p
(
O灴i潮慬) 周攠ty灥

潦 t桥hfilt敲
. C慮ab攠≣潮"ai湳n

潮ly


If 湯n
present, the search will be done by using “startWith”

Result



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d



filt敲e t桥hfilt敲e
t漠慰aly 潮ot桥hmo摥l 湡me



ty灥p (
O灴i潮慬) 周攠ty灥p潦 t桥hfilt敲e
mo摥d猺 t桥hm潤ol猠
f潲o愠扲慮搠
獴慲ai湧nwit栠(潲o捯湴aining) 愠filt敲

withi渠愠r敡lm

Errors

If realm is unknown, a specific error will be
returned

(errorCode 20)

If brand is unknown, a specific error will be returned

(errorCode 22)

If type is not “contains”, a specific error will be returned

E敲e潲o潤攠oㄩ

Request example
s

/restapi/common/1_0/generic/HTC/models/s

/restapi/common/1_0/generic/HTC/models/s?type=contains

Response example
s

{



“realm” : “generic”,

“brand” : “HTC”,

“filter” : “s”,

“models”: [ “Sensation” ]

}


{



“realm” : “generic”,

“brand” : “HTC”,

“filter” : “s”,

“type” : “contains”,

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

12
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


“models”: [ “
Desire”,
“Sensation”
]

}



3.2.6

resolveModel
(
String realm, String[] imeis
, String[] modelIds
, String[] profileURLs
)


Synopsis:

Retrieve brand/model for IMEI
(s)

and /
or Model Id(s)
and / or Profile URL(s)
within a realm.

Description
:

API short name

common

API version

1_0

Method

GET

Base URL

/restapi/common/{version}/{realm}/resolve

Parameter(s)



r敡em: t桥hr敡lm



imei:
(
O灴i潮ol

t桥hIMEI
(s)

/ S彉MEI
(猩



mo摥li

(O灴i潮ol)
t桥hm潤ol I搨猩



灲潦il敵牬: (O灴io湡l) t桥h灲潦il攠UR䰨猩

Result



r敡em:
t桥hr敡lm



摥di捥c

潮攠潲om潲攠
(
IMEI

潲omo摥lid

潲o灲潦il敵牬
)
/扲慮搯m潤敬

o

imei
: the IMEI

(Optional if modelid
/profileurl
used to find the
model)

o

modelid: the model id

(Optional if imei
/profileurl

used to find
the model)

o

profileurl: the profile URL
(Optional if imei/modelid used to
find the model)


o

brand: the brand

o

model: the model

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If IMEI/S_IMEI is
invalid
, a specific error will be returned

for the current
occurrence
(errorCode 24 or 26)

If IMEI/S_IMEI is unknown, a specific error will be returned

for the current
occurrence (errorCode 25 or 28)

If model

I
d is invalid, a specific error will be returned for the current
occurrence (errorCode 29)

If
model Id
is unknown, a specific error will be returned for the current
occurrence

(errorCode 28)

If profile URL is unknown, a specific error will be returned for the current
occurence

(errorCode 27)

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

1
3
/
25

© Copyright 200
5

Sicap
AG

All rights reserved



If no IMEI
,
model Id

or profile URL,
a specific error will be
returned

(errorCode 50)

Request example

/restapi/common/1_0/generic/resolve?
imei
=359068043030750

/restapi/common/1_0/generic/resolve?
imei
=359068043030750&
modelid
=
10
0
65464

Response example

{



“realm” : “generic”,



devices
” :
[

{


imei
”: “359068043030750”,

“brand”: “Nokia”,


model
”: “
7230
”,


}]

}


{



“realm” : “generic”,



devices
” : [

{


imei
”: “359068043030750”,

“brand”: “Nokia”,


model
”: “
7230
”,

},

{


modelid
”: “
10065464
”,



error
Code
”:

“ERROR_CODE“
,


error
”:

“ERROR_
MSG
“,
}]

}









DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

14
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.3

Characteristics API

3.3.1

getCharacteristicsFromIMEI(String realm, String characteristicType, String[] imeis,
String[] filters)


Synopsis:

Retrieve all or specified characteristics
(Raw or Group) of device(s) for
the IMEI(s) within a realm.


Descripti
on
:

API short name

characteristics

API version

1_0

Method

GET

Base URL

/restapi/
characteristics

/{version}/{realm}/
{characteristictype}

Parameter(s)



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥

周攠ty灥p潦 捨慲慣a敲i獴ic

(杲g異u 潲or慷)



imei
: t桥hIMEI(猩



filt敲e
(O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳
. If 湯t 獰散sfi敤e r整畲渠
慬l 慶ail慢a攠v慬略u

Result



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥

周攠ty灥p潦 捨慲慣a敲i獴ic

(杲g異u 潲or慷)



filt敲e
(O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳



摥di捥c
: 潮攠潲om潲攠
im敩
/扲慮搯m潤敬
/filt敲e捨慲c捴敲楳瑩es


o

imei
: the
IMEI

o

brand: the brand

o

model: the model

o

characteristics



“characteristicName”: the characteristic name



“value”: the value of the
c桡牡捴敲i獴ic

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If characteristictype is
invalid
, a specific error will be returned

(errorCode 30)

If IMEI/S_IMEI is invalid, a specific error will be returned for the current
occurence

(errorCode 24 or 26)

If IMEI/S_IMEI is unknown, a specific error will be returned for the current
occurrence (errorCode 25 or 28)

Request example

/restapi/
characteristics
/1_0/generic/
groups?
imei
=35
9068043030750&

imei
=35
9068043030751&filter
=
CAPABILITYGROUP
.
EMAIL
&
filter
=
CAPABIL
ITYGROUP
.
Video_Streaming

Response example

{


DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

15
/
25

© Copyright 200
5

Sicap
AG

All rights reserved



“realm” : “generic”,


“characteristictype” : “
groups
”,



filter
”: [ “
CAPABILITYGROUP
.
EMAIL
”,


CAPABILITYGROUP
.
Video_Streaming
”]
,


devices
” :
[

{


imei
”: “
35
9068043030750
”,

“brand”: “
Nokia ”,


model
”: “
7230
”,


characteristics
”: [

{



CAPABILITYGROUP
.
EMAIL
”:


yes
“,



CAPABILITYGROUP
.
Video_Streaming

: “
yes


}]

}
,

{

“imei”: “
35
9068043030751
”,

“brand”: “Nokia ”,


model
”: “
72
4
0
”,


characteristics
”: [

{



CAPABILITYGROUP
.
EMAIL
”: “
no
“,




CAPABILITYGROUP
.
Video_Streaming


: “no


}]

}
]

}













DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

16
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.3.2

getCharacteristicsFromProfileIURL(String realm, String characteristicType, String[]
profileUrls, String[] filters)


Synopsis:

Retrieve all or specified characteristics
(Raw or Group) of device(s) for
the
profile url
(s) within a realm.


Description
:

API
short name

characteristics

API version

1_0

Method

GET

Base URL

/restapi/characteristics /{version}/{realm}/{characteristictype}

Parameter(s)



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦 捨慲慣a敲i獴i挠(杲g異u 潲or慷)



灲潦il敵牬
: t桥h灲pfil攠畲u
(猩



filt敲e (O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳
. If 湯t 獰散sfi敤e r整畲渠
慬l 慶ail慢a攠v慬略u

Result



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦 捨慲慣a敲i獴i挠(杲g異u 潲or慷)



filt敲e
(O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳



摥di捥c
: 潮攠潲om潲攠
灲pfil敵el
/扲慮搯m潤ol/filt敲ech慲慣a敲楳ei捳c

o

profileurl: the profile url

o

brand: the brand

o

model: the model

o

characteristics



“characteristicName”: the characteristic name



“value”: the
v慬略u潦 t桥hc桡牡捴敲i獴ic

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If characteristictype is unknown, a specific error will be returned

(errorCode
30)

If profile URL is unknown, a specific error will be returned for the current
occurence

(errorCode 27)

Request example

/restapi/characteristics/1_0/generic/
raw
?
profileurl
=
http%3a%2f%2fwww.sica
p.com%0d%0a
&
profileurl
=
http%3a%2f%2fwww.sicap
-
france.com%0d%0a
&
filter=
HardwareExt.batteryType
&filter=
HardwareExt.de
viceType

Response example

{



“realm” : “generic”,

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

17
/
25

© Copyright 200
5

Sicap
AG

All rights reserved



“characteristictype” : “
raw
”,



filter
”: [ “
HardwareExt.batteryType
”, “
HardwareExt.deviceType
” ]
,


devices

: [

{


profileurl
”: “
http://www.sicap.com
”,

“brand”: “
Nokia ”,


model
”: “
7230
”,


characteristics
”: [

{



“HardwareExt.batteryType”: “Li
-
Ion”,





“HardwareExt.deviceType”:
“Mobile Phone”

}]

},

{


profileurl
”: “
http://www.sicap
-
france.com
”,

“brand”: “
Nokia ”,


model
”: “
7240
”,


characteristics
”: [

{


“HardwareExt.batteryType”: “Li
-
Ion”,





“HardwareExt.deviceType”: “Mobile Phone”

}]

}]

}















DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

18
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.3.3

getCharacteristicsFromModelId(String realm, String characteristicType, String[]
modelIds, String[] filters)


Synopsis:

Retrieve all or specified characteristics
(Raw or Group) of device(s) for
the
model id
(s) within a realm.


Description
:

API short name

characteristics

API version

1_0

Method

GET

Base URL

/restapi/characteristics /{version}/{realm}/{characteristictype}

Parameter(s)



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦 捨慲慣a敲i獴i挠(杲g異u 潲or慷)



mo摥lid
: t桥h
mo摥l id
(猩



filt敲e (O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳
. If 湯t 獰散sfi敤e r整畲渠
慬l 慶ail慢a攠v慬略u

Result



r敡em: t桥hr敡lm



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦
捨慲慣a敲i獴i挠(杲g異u 潲or慷)



filt敲e
(O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳



摥di捥c
: 潮攠潲om潲攠
m潤敬id
/扲慮搯m潤ol/filt敲e捨cr慣a敲楳瑩捳c

o

modelid
: the
model id

o

brand: the brand

o

model: the model

o

characteristics



“characteristicName”: the characteristic name



“value”: the value of the characteristic

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If characteristictype is unknown, a specific error will be

returned

(errorCode
30)

If model Id is invalid, a specific error will be returned for the current
occurence

(errorCode 29)

If model Id is unknown, a specific error will be returned for the current
occurrence

(errorCode 28)

Request example

/restapi/characteristics/1_0/generic/raw?
modelid
=
10012
&
modelid
=
10013
&filt
er=HardwareExt.batteryType&filter=HardwareExt.deviceType

Response example

{



“realm” : “generic”,

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

19
/
25

© Copyright 200
5

Sicap
AG

All rights reserved



“characteristictype” : “raw”,



filter
”: [ “
HardwareExt.batteryType
”, “
HardwareExt.deviceType
” ],


devices

: [

{

“modelid”: “
10012
”,

“brand”: “Nokia ”,


model
”: “
7230
”,


characteristics
”: [

{


“HardwareExt.batteryType”: “Li
-
Ion”,





“HardwareExt.deviceType”: “Mobile Phone”

}]

},

{

“modelid”: “
10013
”,

“brand”: “Nokia ”,


model
”: “
7240
”,


characteristics
”: [

{


“HardwareExt.batteryType
”: “Li
-
Ion”,





“HardwareExt.deviceType”: “Mobile Phone”

}]

}]

}















DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

20
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


3.3.4

getCharacteristicsFromRealmBrandModel
(String realm, String brand, String model,
String characteristictype, String[] filters)


Synopsis:

Retrieve all or specified characteristics
(Raw or Group) of device(s) for
the
brand and model

within a
realm.


Description
:

API short name

characteristics

API version

1_0

Method

GET

Base URL

/restapi/characteristics /{version}

/{realm}/{brand}/{model}/{characteristictype}

Parameter(s)



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d



mo摥l : t桥hmo摥d



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦 捨慲慣a敲i獴i挠(杲g異u 潲or慷)



filt敲e (O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳
. If 湯t 獰散sfi敤e r整畲渠

l 慶ail慢a攠v慬略u

Result



r敡em: t桥hr敡lm



扲慮携 t桥h扲慮d



mo摥l: t桥hm潤ol



捨慲慣c敲i獴i捴y灥p 周攠ty灥p潦 捨慲慣a敲i獴i挠(杲g異u 潲or慷)



filt敲e
(O灴i潮ol) 周攠filt敲e猩 f潲o捨慲c捴敲楳ei捳



捨慲慣c敲i獴i捳c


o

“characteristicName”: the characteristic
湡me

o

“value”: the value of the characteristic

Errors

If realm is unknown, a specific error will be returned

(errorCode 20)

If
brand

is unknown, a specific error will be returned

(errorCode 22)

If
model

is unknown, a specific error will be returned

(errorCode 23)

If characteristictype is unknown, a specific error will be returned

(errorCode
30)

Request example

/restapi/characteristics/1_0/generic/
Nokia/N95/
raw?filter=HardwareExt.batter
yType&filter=HardwareExt.deviceType

Response example

{



“realm” : “generic”,


“brand”: “Nokia”,


“model”: “N95”,

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

21
/
25

© Copyright 200
5

Sicap
AG

All rights reserved



“characteristictype” : “raw”,



filter
”: [ “
HardwareExt.batteryType
”, “
HardwareExt.deviceType
” ],



characteristics
”: [


{


“HardwareExt.batteryType”: “Li
-
Ion”,




“HardwareExt.deviceType”: “Mobile Phone”


}]

}










3.3.5

getCharacteristics (String[] types)


Synopsis:

Retrieve the list of available "type" characteristics keys
.


Description
:

API short name

characteristics

API version

1_0

Method

GET

Base URL

/restapi/characteristics /{version
}/list

Parameter(s)



ty灥p:
Ty灥⡳p 潦 t桥h捨慲a捴敲楳瑩e猠k敹献 M畳u 扥b≧"潵灳∠潲o≲慷"

Result



“characteristics_groups” or “raw_characteritics”
W li獴 潦 t桥h
捨慲慣c敲i獴i捳

f潲oty灥p

Errors

If
type

is unknown, a specific error

for the occurence

will be returned

(errorCode 30)


Request example

/restapi/characteristics/1_0/
list?type=groups&type=raw

/restapi/characteristics/1_0/
list?type=groups

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

22
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


Response example

{






“characteristic
s
_groups
” : [



CAPABILITYGROUP
.
Video_Streaming
”,



CAPABILITYGROUP
.MMS
”,



GENERATION
.
smartphone
”,



CAPABILITYGROUP
.

CAPABILITYGROUP_PIN_1_to_4_Digits

]
,



raw_
characteristic
s” : [


“HardwareExt.batteryType”,



HardwareExt.deviceType”,


“HardwareExt.maxStillCameraResolution”,


“HardwareExt.maxVideoCameraResolution”,


“HardwareExt.mobilePhoneDesign”,


“NetworkCharacteristics.supportedBearers”,


“SoftwarePlatform.oSName”,



SoftwarePlatform.oSVendor” ]

}
]

}


{

“characteristics_groups” : [



CAPABILITYGROUP
.
Video_Streaming
”,



CAPABILITYGROUP
.MMS
”,



GENERATION
.
smartphone
”,



CAPABILITYGROUP
.

CAPABILITYGROUP_PIN_1_to_4_Digits


]

}

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

23
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


4

Annexe

4.1

Error code & message


Error code

Error message

10

Malformed URL

11

Error during DRB load

12

File is not found on the server

13

DRB Format is invalid

14

A DRB import is already in progress

20

Realm is not present in the DRB

21

Type accepts only 'contains' value

22

Brand

is not present in the DRB

23

Model is not present in the DRB

24

IMEI is not valid

25

IMEI is not present in the DRB

26

S_IMEI is not valid

27

Profile URL is not present in the DRB

28

Model ID is not present in the DRB

29

Model ID is not valid

30

Characteristic type is not valid

50

Parameter is mandatory











DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

24
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


4.2

Terms & Definition

The definitions given are intended in the context of the Sicap HUS Tool, and apply to all the
requirements contained in this document. These definitions may be
overridden in the context of a
specific requirement.


Term

Definition

ADM

Advanced Device Management

ADD

Automatic Device Detection

API

Application Programming Interface

APN

Access Point Name

CRUD
-
L

Create, Read, Update, Delete, List

Operations
allowing management of data in database.

DMC

Device Management Centre

SICAP product used to manage user devices remotely.

DRB

Device Resource Base

Archive name containing device knowledge. This archive is a key file in SICAP
products, as it allows
spreading device knowledge to other products. Its content
must be well
-
defined, and data exported in such file must be safe, to avoid
cascading issues. A DRB archive may contain devices definitions (brand, model,
etc…), attributes (screen configuration, su
pported encoding for MMS, etc…), and
additional resources (help files, images, etc…).

GPRS

General Packet Radio Service

GUI

Graphical User Interface

HTTP

Hyper Text Transfer Protocol

HTTPS

Hyper Text Transfer Protocol Secure

IM

Instant Messaging

IMEI

International Mobile Equipment Identity

IMSI

International Mobile Subscriber Identity

IP

Internet Protocol

ISDN

Integrated Service Digital Network

KPI

Key Performance Indicator

MMG

Multimedia
Mobile

Gateway

MMS

Multimedia Messaging Service

MO
-
SMS

/ SMS
-
MO

Mobile Originated SMS

MSISDN

Mobile Station ISDN Number

A number identifying a subscription in a UMTS or GSM network.

N/A

Not Applicable

Normalization

Normalization is a process aiming at saving an input value always with the same
format. Such

process is often used when there are needs to group objects or to
compute statistics.

DRS

RESTful API

Business Confidenti
al



Sicap AG

Saegestrasse 65

3098 Koeniz / Berne

Switzerland

Document id

Valid from

Document Version

flashypumpkincenter_ec84506f
-
e378
-
4750
-
bc92
-
3eec2e01ece3.docx

7/25/2012

1.3

25
/
25

© Copyright 200
5

Sicap
AG

All rights reserved


Term

Definition

In this specification, device profiles attributes are normalized using their
associated metadata.

OMA

Open Mobile Alliance

OMA DM

OMA Device Management

OMA DM CP

OMA
DM Continuous Provisioning

OTA

Over The Air

PIN

Personal Identification Number

RESTful

A RESTful web service (also called a RESTful web API) is a web service
implemented using HTTP and the principles of REST.

See
http://en.wikipedia.org/wiki/Representational_state_transfer

for more details.

RMI

Remote Method Invocation

SIM

Subscriber Identity Module

SIP

Session Initiation Protocol

SMS

Short Message Service

SOAP

Simple Object Access Protocol

SVN

SubVersioN

A version control system.

SYNCML

Synchronization Markup Language

TCP/IP

Transmission Control Protocol / Internet Protocol

UAP

User Agent Profile

An UAP describes the capabilities
of a mobile device, and is generally provided by
vendors in an XML or RDF file.

UML

Unified Markup Language

Validation

Validation is a process aiming at ensuring no invalid value can be saved in a
system. It provides a higher security to a system, and li
mits unexpected faults in
children processes using the same value.

In this specification, device profiles attributes are validated using their associated
metadata.

WAP

Wireless Application Protocol

WBXML

Wap Binary Extensible Markup Language