Getting started with the SOAP API

Find herewith our SOAP API service description.

Connecting to the service

First of all, you have to get the URL of the endpoint. You can find it inside the Management > System > Web service page of your account.

It will look like:

https://ws-mn1.mag-news.it/ws/wsapi?wsdl

Then, you have to obtain a valid set of credentials to access API methods. There are two possibilities:

• Use OAuth 2.0 authentication (click here to learn how to get an access_token)
• Use legacy username/password based authentication

In order to issue requests using your credential, you have to fill in the Credentials parameter for each call.

It is recommended to use OAuth 2.0 authentication scheme, basically for these reasons:

• Your application will not have to keep a copy of real user credentials but just an "access_token"
• If the user changes username or password you have to update your application configuration
• Username and password are less "secure" then access_tokens: access_tokens are generated using safe algorithms and are "longer"
• Every access_token needs to be "refreshed", so if an access_token has been stolen it will be used for a little time
• When you are using OAuth 2.0 you will have fine-grained control of your client application and you can revoke an application permits without modifying user credentials and permissions.

How to use an access_token

If you want to use OAuth 2.0 based authentication, just fill in the Credentials parameter only with this value:

• password: The OAuth 2.0 access_token

If you want to use username/password based authentication, fill in the Credentials parameter with these values:

• customerId: Customer login/ID that identifies the magnews account in use
• username: Username that the editor uses to login to the magnews account
• password: Password to access to the magnews account

There is an hybrid approach: you can use the username/password OAuth 2.0 flow in order to get an access_token from the username/password credentials of the user.

To get to know the <customerId> you have to access to magnews and click on "Account information" on the right top of the page. In the page that is subsequently opened, you can see the account ID.

Authentication occurs through an explicit passage of a Credentials structure, as a parameter of any operation:

Credentials {
    String username;
    String password;
    int customerId;
    int type;
    String extra;
}

If type is equals to '0' you will get a plain username/password authentication, but you can also leave this parameter empty.

E.g.: A user with username = 'test', customerId = 876, password= 'hello' must login with these credentials

USERNAME = 'test'
PASSWORD = 'hello'
CUSTOMERID = 876    

If you leave the username empty or type is equals to '2', the authentication is OAuth 2.0 based, in field you put your access_token.

PASSWORD = access_token

Permissions required for each web service request

Every web service request is executed using the role of the user which is authenticated (using username/password or the access_token).

For instance, if you want to get data of a contact for database 1, the user that is executing the request needs to have the permission to export data for database 1.

For simple integrations, it is recommended to create a specific user dedicated to the Web Service use and configure on it a suitable security role.

For more complex integrations, which use more than one user of the platform, let the system handle the permissions using every user's security role.

Localization of parameters and time zones

Sometimes API calls need to receive parameters (or output data) using string values: every date, datetime and decimal number is always formatted using the localization settings of the user who issued the request.

Dates and datetime values represented as strings are always represented using the time zone of the user who issued the request.