opensrs publishing service api command reference · 2019-01-15 · publishing service api commands...

OpenSRS Publishing ServiceAPI Command Reference

October 22, 2013

Table of ContentsIntroduction.........................................................................................4

Purchasing goMobi Services................................................................4Integrating with OpenSRS..................................................................4Publishing Service API error response codes.........................................5

Publishing Service API commands...........................................................7create_alias......................................................................................7

Request parameters for create_alias................................................7Response parameters for create_alias..............................................8Examples for create_alias...............................................................8

create (publishing)..........................................................................10Request parameters for create (publishing).....................................10Response parameters for create (publishing)...................................11Examples for create (publishing)....................................................12

delete_alias....................................................................................14Request parameters for delete_alias...............................................14Response parameters for delete_alias.............................................14Examples for delete alias..............................................................15

delete (publishing)..........................................................................17Request parameters for delete (publishing).....................................17Response parameters for delete (publishing)...................................17Examples for delete (publishing)....................................................18

disable (publishing).........................................................................20Request parameters for disable (publishing)....................................20Response parameters for disable (publishing)..................................20Examples for disable (publishing)...................................................21

2

enable (publishing)..........................................................................23Request parameters for enable publishing.......................................23Response parameters for enable publishing.....................................23Examples for enable publishing......................................................24

generate redirection code.................................................................26Request parameters for generate_redirection_code..........................26Response parameters for generate_redirection_code........................27Examples for generate_redirection_code.........................................27

get_alias_list..................................................................................30Request parameters for get_alias_list.............................................30Response parameters for get_alias_list...........................................30Examples for get_alias_list............................................................31

get_control_panel_url......................................................................34Request parameters for get_control_panel_url.................................34Response parameters for get_control_panel_url...............................35Examples for get_control_panel_url................................................35

get service info...............................................................................38Request parameters for get_service_info........................................38Response parameters for get_service_info......................................38Examples for get_service_info.......................................................40

let expire (publishing)......................................................................43Request parameters for let expire (publishing).................................43Response parameters for let expire (publishing)...............................43Examples for let expire (publishing)...............................................44

update publishing............................................................................46Request parameters for update publishing.......................................46Response parameters for update publishing.....................................46Examples for update publishing.....................................................47

Revisions and Updates.........................................................................49

3

IntroductionThe OpenSRS Publishing Services allows you and your customers to quickly and easily create mobile domains that make your customers’ businesses easily available to mobile users.

This guide provides information about the commands that are specific to the OpenSRS Publishing Service.

Purchasing goMobi ServicesWhen a customer purchases the goMobi service, a mobile site is set up on the specified mobile hostname. The mobile website can be set up using a subdomain or an entire domain, as long as the mobile hostname is different fromwhat is used for the existing website.

To fully configure the mobile service, the DNS needs to be configured for the mobile hostname and redirection code needs to be installed on the current website.

The redirection code sends visitors to the appropriate version of the website, depending on the device that they're using. For example, if they are using a mobile phone to access the website, they will see the mobile version of the site.

It's not necessary to specify the full website when setting up the goMobi service (though if submitted, it must be a valid site). However, for mobile phones to be re-directed to the mobile version of a website, the redirection code must be in place, and the source domain must be specified.

An easy-to-use goMobi control panel allows your customers to add and configure their mobile website content.

Integrating with OpenSRSYou can implement the OpenSRS Publishing Service by setting up either a partial or a full integration with the OpenSRS API.

Partial integrationA partial integration allows you to integrate with the OpenSRS API to processpurchases of the goMobi service. You can then direct your customers to the unbranded self management portal that is provided by OpenSRS so that theycan access the goMobi control panel to set up and manage their mobile websites.

This interface requires a username and password as access credentials. The interface is accessible at a URL that includes your Reseller username.

4

Example: https://[Reseller_username].domainadmin.com

The self management interface allows the customer to manage one or more mobile domains, access the goMobi control panel, and generate redirection code.

In this case, when provisioning the goMobi service, you must supply your customer with a username and password to access the self management portal.

New orders for an existing user account require only that the username be submitted.

Important: If customer credentials are not supplied in the provisioning request, the customer profile will not be created and it cannot be added at a later time.

Full integrationYou can also choose to implement a full integration with the OpenSRS API and build your own portal for your customers to use to set up and manage the mobile website service.

In this case, end user authentication information does not need to be provided, nor does a user account need to be created. By leveraging the commands described in this guide, you can build a portal to allow your customers to fully manage the mobile website service.

The OpenSRS API allows you to generate the redirection code when requested by a customer. It also allows you to generate a temporary unique URL that can be used to load the goMobi control panel within a frameset of an existing web portal.

In addition, there are commands that allow you to update and manage the configuration details and lifecycle of the goMobi service.

Publishing Service API error response codes

Code Response text/Explanation

997

• Could not complete API request: 500 Internal Server Error.

• It is not possible to reactive a subscription which is not suspended!

• It is not possible to use expired subscription for the action!

998 • Alias "abc.123.com" does not exist.

5

Code Response text/Explanation

• Alias has been already used!

• Cannot access goMobi control panel due to current status.

• Cannot delete due to current status.

• Cannot disable due to current status.

• Cannot re-enable due to current status.

• Domain "abc.123.com" does not exist for service type "gomobi".

• Domain garbageabc123: Malformed domain.

• Email address is invalid. (RFC822)

• Generating code for programming language '$programming_language' not supported.

• Invalid current password.

• Password contains illegal characters.

• Password must be at least 8 characters in length.

• Service already exists at provider.

• Service already exists for abc.123.com.

• There is a problem with the source domain. It must be in theformat \'www.yourdomain.com\'. Paths are also permitted (e.g. www.yourdomain.com/path/index.html).

• The source domain, and mobile domain cannot be the same.

• Username already exists.

• Username contains illegal characters.

• Username must be at least 6 characters in length.

6

Publishing Service API commands

create_alias

Description

Action & objectaction = create_alias

object = publishing

UsageCreates an alias for a mobile domain. You can create up to five aliases per subscription so that multiple hostnames can point to the same goMobi page; however, each alias must be created separately.

Important: Ensure that the DNS for each of the alias hostnames points to lb.goMobi.info.

Request parameters for create_alias

Standard parametersaction = create_alias

object = publishing

attributes

AttributesParameters within the attributes associative array are described below.

Parameter name

Obligation Definition/Value

domain Required The name of the mobile domain for which you want to create aliases.

hostname Required The name of the alias.

service_type Required The type of Publishing service.

Allowed value is gomobi.

7

Response parameters for create_alias

Standard parametersaction = reply

object = publishing

is_success = a Boolean is returned, indicating success or failure of the request

response_code = response code indicating outcome of the request

response_text = message describing the outcome of the request

Examples for create_alias

Request<?xml version='1.0' encoding="UTF-8" standalone="no" ?>

<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">

<OPS_envelope>

<header>

<version>0.9</version>

</header>

<body>

<data_block>

<dt_assoc>

<item key="protocol">XCP</item>

<item key="action">create_alias</item>

<item key="object">publishing</item>

<item key="attributes">

<dt_assoc>

<item key="service_type">gomobi</item>

<item key="domain">example.com</item>

<item key="hostname">example.net</item>

</dt_assoc>

</item>

</dt_assoc>

8

</data_block>

</body>

</OPS_envelope>

Response<?xml version='1.0' encoding="UTF-8" standalone="no" ?>


<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">REPLY</item>

<item key="object">PUBLISHING</item>

<item key="response_text">Created alias 'example.net' for 'example.com'.</item>

<item key="response_code">200</item>

<item key="is_success">1</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

9

create (publishing)

Description

Action & objectaction = create

object = publishing

UsageCreates a new goMobi domain.

Request parameters for create (publishing)

Standard parametersaction = create

object = publishing

attributes


Parameter name Obligation Definition/Value

domain Required The name of the mobile domain that you want to create.

end_user_auth_info Optional A list of the end user account information.

For more information, see the End user auth info table below.



source_domain Optional The name of the domain on which the new mobile web page will be based.

10

End user auth infoParameters within the end_user_auth_info associative array are described below.

If you are adding the service to an existing account, you only need to specifythe username; if you are creating a new account, you must specify username, email_address,and password.

Note: If you do not specify a username and password, the service will work; however, the domain owner will not be able to access the end user control panel at domainadmin.com. In that case, you can either provision thedomain for your customer or you can provide your own end user interface.

Parameter name


email_address Required if end_user_auth_info isspecified and this is a new account

The domain owner's email address.

password Required if end_user_auth_info isspecified and this is a new account

The password associated with the Publishing service. The password must be at least 8 characters long.

username Required if end_user_auth_info isspecified

The username associated with the Publishing service. The username must be at least 6 characters long.

Response parameters for create (publishing)


object = publishing




11

Examples for create (publishing)



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">CREATE</item>



<dt_assoc>


<item key="domain">example.net</item>

<item key="source_domain">example.com</item>

<item key="end_user_auth_info">

<dt_assoc>

<item key="email_address">[email protected]</item>

<item key="password">BigPWTest</item>

<item key="username">danny1234</item>

</dt_assoc>

</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

12



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Publishing service created</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

13

delete_alias

Description

Action & objectaction = delete_alias

object = publishing

UsageDeletes a goMobi domain alias.

Request parameters for delete_alias

Standard parametersaction = delete_ALIAS

object = publishing

attributes


Parameter name


domain Required The name of the mobile domain whose alias you want to delete.

hostname Required The alias that you want to delete.



Response parameters for delete_alias


object = publishing

14




Examples for delete alias



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">delete_alias</item>



<dt_assoc>



<item key="hostname">example.net</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

15

Response <?xml version='1.0' encoding="UTF-8" standalone="no" ?>


<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Deleted alias

'example.net' for

'example.com'.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

16

delete (publishing)

Description

Action & objectaction = delete

object = publishing

UsageDeletes a goMobi domain.

Warning: This command deletes the account immediately.

Request parameters for delete (publishing)

Standard parametersaction = delete

object = publishing

attributes


Parameter name


domain Required The name of the mobile domain that you want todelete.



Response parameters for delete (publishing)


object = publishing


17



Examples for delete (publishing)



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">DELETE</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

18

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Deleted 'gomobi' service for 'example.net'.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

19

disable (publishing)

Description

Action & objectaction = disable

object = publishing

UsageDisables a goMobi domain. This command causes the mobile domain to be inaccessible; however, you are still charged for the service, and you can re-enable the domain by using the enable (publishing) command. If you want tostop billing, you need to delete the account by using the delete (publishing) command.

Request parameters for disable (publishing)

Standard parametersaction = disable

object = publishing

attributes


Parameter name


domain Required The name of the mobile domain that you want todisable.



Response parameters for disable (publishing)


object = publishing

20




Examples for disable (publishing)



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">DISABLE</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



21

<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Disabled 'gomobi' service for 'example.net'.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

22

enable (publishing)

Description

Action & objectaction = enable

object = publishing

UsageRe-enables a goMobi domain that has been d isabled or set to l et-expire.

Request parameters for enable publishing

Standard parametersaction = enable

object = publishing

attributes


Parameter name


domain Required The name of the mobile domain that you want toenable.



Response parameters for enable publishing


object = publishing



23


Examples for enable publishing



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">ENABLE</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


24

</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Enabled 'gomobi' service for 'example.net'.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

25

generate redirection code

Description

Action & objectaction = generate_redirection_code

object = publishing

UsageGenerate code that redirects visitors to either the source domain or the mobile domain, depending on the device they’re using.

Request parameters for generate_redirection_code

Standard parametersaction = generate_redirection_code

object = publishing

attributes



domain Required The name of the mobile domain that you want to let expire.

programming_language Required The programming language for the code.

Allowed values are:

asp

htaccess

javascript

jsp

php



26

Response parameters for generate_redirection_code


object = publishing





Parameter name


redirection_code Required The code that you insert in your source website that redirects visitors to the source or the mobile site depending on the device they're using to access it.

Examples for generate_redirection_code



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


27

<item key="action">GENERATE_REDIRECTION_CODE</item>



<dt_assoc>

<item key="programming_language">javascript</item>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Got GoMobi redirection code (javascript) for 'example.net'</item>




<dt_assoc>

28

<item key="redirection_code"><script type="text/javascript" src="http://detect.deviceatlas.com/redirect.js?d=http://example.com&m=http://example.net"></script></item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

29

get_alias_list

Description

Action & objectaction = get_alias_list

object = publishing

UsageReturns a list of the aliases associated with the specified domain.

Request parameters for get_alias_list

Standard parametersaction = get_alias_list

object = publishing

attributes



domain Required The name of the mobile domain.

service_type RequiredThe type of Publishing service.


Response parameters for get_alias_list


object = publishing




attributes

30

AttributesIf the request is successful, the attributes associative array may include the following:

Parameter name


aliases Returned if is_success = true

The list of the aliases associated with the specified domain.

domain Returned if is_success = true

The name of the mobile domain.

Examples for get_alias_list



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">get_alias_list</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

31

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>






<item key="response_text">Service information retrieved.</item>


<dt_assoc>


<item key="aliases">

<dt_array>

<item key="0">example.net</item>

<item key="1">example.org</item>

<item key="2">example.info</item>

<item key="3">example.biz</item>

<item key="4">example.us</item>

</dt_array>

</item>

</dt_assoc>

32

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

33

get_control_panel_url

Description

Action & objectaction = get_control_panel_url

object = publishing

UsageReturns the URL for the goMobi control panel that you use to define the appearance of the mobile site.

Important: This link is only available for 5 minutes.

Request parameters for get_control_panel_url

Standard parametersaction = get_control_panel_url

object = publishing

attributes


Parameter name



language Optional The language in which the goMobi Control Panel is displayed. The URL that is returned will be for the Control Panel in the specified language.

The default is English.

Allowed values are:

• de—German

• en—English (US)

• en-GB—English (UK)

• es—Spanish

• fr—French

• it—Italian

34

Parameter name


• ja—Japanese

• nl—Dutch

• pt—Portuguese

• ru—Russian

• sl—Slovenian

• zh-CN—Chinese



Response parameters for get_control_panel_url


object = publishing




attributes


Parameter name


control_panel_url Required The URL for the goMobi control panel that you use to define the appearance of the mobile site.

Examples for get_control_panel_url



35

<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">GET_CONTROL_PANEL_URL</item>



<dt_assoc>



<item key="language">es</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


36





<item key="response_text">Got GoMobi control-panel URL for 'example.net'.</item>


<dt_assoc>

<item key="control_panel_url">https://cpsandbox.instantmobilizer.com/69/example.net/1290717040/G8%2BIDXjU0hyJ%2FnKMp7%2BJAwKX9T7mVg7Q%2BPcKA%2FSDN1hAFHSk%2FvMLQyBhQyXwZWj66TWHJ0%2BWPppK%0A70VKGNodLaiepIiIvQU9bpPu63O%2BsxmORtu4cQLzyKGQVYstjYhozrXhFJsGDK%2B30zU%2FvZEmalC4%0AL4x5qm9aQ28i75gUEb4%3D%0A/en</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

37

get service info

Description

Action & objectaction = get_service_info

object = publishing

UsageGets information about the goMobi service.

Request parameters for get_service_info

Standard parametersaction = get_service_info

object = publishing

attributes


Parameter name





Response parameters for get_service_info


object = publishing




attributes

38


Parameter name


aliases Returned if aliases exist and is_success = true

The list of aliases associated with the domain.

billing_date Returned if is_success = true

The next billing date for the goMobi service.

creation_date Returned if is_success = true

The date the goMobi service was purchased.

domain Returned if is_success = true

The name of the mobile domain.

gomobi Returned if is_success = true

Lists information about the goMobi service.

For more information, see the gomobi table below.

status Returned if is_success = true

The current status of the goMobi service.

Allowed values are:

• active—The service is active.

• deleted—The service is no longer active and cannot be re-enabled.

• disabled—The mobile site is not accessible, but the Reseller is still being billed.

• insufficient funds—The Reseller has insufficient funds in their account to coverthe charges for the current billing period.

• let expire—The service will expire at the end of the current billing period.

• processed—The order has been processed.

39

gomobiParameters within the gomobi associative array are described below.

Parameter name


source_domain Required The name of the domain on which the mobile domain is based.

Examples for get_service_info



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">GET_SERVICE_INFO</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

40



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>






<item key="response_text">Service information retrieved.</item>


<dt_assoc>


<item key="gomobi">

<dt_assoc>

<item key="source_domain">example.com</item>

</dt_assoc>

</item>


<item key="creation_date">2010-11-26 12:33:03 UTC</item>

<item key="status">active</item>

<item key="aliases">

<dt_array>

<item key="0">example.net</item>

<item key="1">example.org</item>

<item key="2">example.info</item>

41

<item key="3">example.biz</item>

<item key="4">example.us</item>

</dt_array>

</item>

<item key="billing_date">2010-12-26 12:33:03 UTC</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

42

let expire (publishing)

Description

Action & objectaction = let_expire

object = publishing

UsageSets a goMobi domain to expire at the end of the billing period. Until that time, you can re-enable the domain by using the enable (publishing) command.

Request parameters for let expire (publishing)

Standard parametersaction = let_expire

object = publishing

attributes


Parameter name


domain Required The name of the mobile domain that you want tolet expire.



Response parameters for let expire (publishing)


object = publishing


43



Examples for let expire (publishing)



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>


<item key="action">LET_EXPIRE</item>



<dt_assoc>



</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>



<OPS_envelope>

44

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Let 'gomobi' service for 'example.net' expire.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

45

update publishing

Description

Action & objectaction = update

object = publishing

UsageChanges the name of the mobile domain, and, optionally, changes the domain from which the mobile domain gets its content.

Request parameters for update publishing

Standard parametersaction = update

object = publishing

attributes


Parameter name



new_domain Optional The new name of the mobile domain.



source_domain Required The name of the domain on which the mobile domain content is based.

Response parameters for update publishing


object = publishing

46




Examples for update publishing



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>



<item key="action">UPDATE</item>


<dt_assoc>



<item key="source_domain">example303.com</item>

<item key="new_domain">example123.net</item>

</dt_assoc>

</item>

</dt_assoc>

</data_block>

</body>

</OPS_envelope>

47



<OPS_envelope>

<header>


</header>

<body>

<data_block>

<dt_assoc>




<item key="response_text">Updated 'gomobi' service for 'example.net' with source-domain 'example303.com' and new domain 'example123.net'.</item>



</dt_assoc>

</data_block>

</body>

</OPS_envelope>

48

Revisions and Updates

October 22, 2013

• Added additional languages to the get_control_panel_url request.

August 14, 2012

• Added language to the list of request parameters for get_control_panel_url. When submitted, the URL that is returned is for the control panel in the specified language.

May 17, 2012

• Added htaccess to the list of available languages for generate_redirection_code.

• Added the following new commands for Publishing:• create_alias—Creates one or more goMobi aliases.• delete_alias—Deletes a goMobi domain alias.• get_alias_list—Returns a list of aliases for the specified domain.

• The get_service_info command now returns a list of the aliases for a goMobi domain.

• Incremented version to 4.0.6.

49

opensrs publishing service api command reference · 2019-01-15 · publishing service api commands...

Documents