Web API in Detail

The SmartStore.Net Web API in detail

The SmartStore.NET Web API consist of two sections. The main OData section /odata/v1/ provides access to all entity related resources and the general API section /api/v1/ is used for "all other resources" like uploading product images for example. The OData section is the more important one and recommended to start to work with.

You can consume API services through HTTP calls in a RESTful manner by using HTTP methods GET, POST (insert), PUT (update), PATCH (partially update) and DELETE. OData options (such a $filter, $top, $select, etc.) and API specific options (such as SmNetFulfillCountry) can be transferred through query strings.

Paging is required if you want to query multiple records. You can do that with OData $skip and $top. The maximum value for $top is returned in the SmartStore-Net-Api-MaxTop header field.

A request body needs to be UTF8 encoded.

Request HTTP header fields

User-Agent (optional): Short description of the API consumer. Example: My shopping data consumer v.1.0

Accept (required): The desired response format. Example for JSON: application/json.

Accept-Charset (required): Always UTF-8.

Content-Type and Content-Length (conditional): Necessary for the methods POST, PUT, and PATCH, if new data is sent via the HTTP body. Example: application/json; charset=utf-8

Content-MD5 (optional): For methods POST, PUT, and PATCH. Authentication provides the error ContentMd5NotMatching if the hash does not match the one calculated by the server. This header field has no safety relevance, as the content is carried out using the HMAC signature. Example: lgifXydL3FhffpTIilkwOw==

SmartStore-Net-Api-Date (required): Date and time of the request as Coordinated Universal Time (UTC). Use ISO-8601 format including milliseconds. Example: 2013-11-09T11:42:48.4715986Z

SmartStore-Net-Api-PublicKey (required): The public key of a member. Example: 0c6b33651708eb09c8a8d6036b79d739

Authorization (required): The authorization schema and the HMAC signature, separated by a space. The schema is SmNetHmac plus its version. Example: SmNetHmac1 +yvONYvJmQl19omu1uE3HVlQ7afd7Qqkk8DrNrfUbe8=

Example of a complete request header:

Response HTTP header fields

SmartStore-Net-Api-Version: The highest API version supported by the server (unsigned integer) and the version of the installed API plugin (floating-point value). The API version is only increased when there is a fundamental break in API development without the ability of backward compatibility. The plugin version is typically increased when the API has been extended, for example when new resources have been added. Example: 1 1.0

SmartStore-Net-Api-Date: The current server date and time in ISO-8601 UTC. Example: 2013-11-11T14:35:33.7772907Z

SmartStore-Net-Api-MaxTop: The maximum value for OData $top option. Required for client-driven paging. The default value is 120. The merchant can change that value by a configuration setting.

SmartStore-Net-Api-HmacResultDesc: Short description of the result of the HMAC authentication. Only returned if the authentication has failed. Example: InvalidTimestamp

SmartStore-Net-Api-HmacResultId: Unsigned ID that represents the result of the HMAC authentication. Only returned if the authentication has failed. Example: 5

WWW-Authenticate: The name of the authentication method that failed. Note that CORS requests can lead to multiple header fields. The SmartStore.Net Web API returns SmNetHmac1 if its authentication has failed.

List with HmacResultId and HmacResultDesc:

• 0 Success

• 1 FailedForUnknownReason

• 2 ApiUnavailable

• 3 InvalidAuthorizationHeader

• 4 InvalidSignature

• 5 InvalidTimestamp

• 6 TimestampOutOfPeriod

• 7 TimestampOlderThanLastRequest

• 8 MissingMessageRepresentationParameter

• 9 ContentMd5NotMatching

• 10 UserUnknown

• 11 UserDisabled

• 12 UserInvalid

• 13 UserHasNoPermission

Frequent HTTP response status codes

200 OK: Standard response for successful HTTP requests.

201 Created: The request has been fulfilled and resulted in a new resource being created.

204 No Content: The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.

400 BadRequest: There is something wrong with the request, e.g. an invalid or missing parameter.

401 Unauthorized: Authentication failed or the user is not authorized (in case of UserHasNoPermission). There is no content returned because no access can be granted to the client.

403 Forbidden: The resource cannot be accessed through the API, e.g. for security reasons.

404 Not found: The requested resource cannot be found.

405 Method Not Allowed: The requested resource does not support the wanted HTTP method.

406 Not Acceptable: The requested resource is only capable of generating content that is not acceptable according to the Accept headers sent in the request. Typically generated by OData provider.

422 Unprocessable entity: The request is OK, but its processing failed due to semantic issues or unprocessable instructions. For example, putting the payment status of an order to an unknown value.

500 Internal Server Error: A generic error message, given when no more specific message is suitable.

501 Not implemented: Accessing the resource even though the API has not (yet) been implemented.

503 Service Unavailable: The resource is not accessible, for example because the API plugin is in an unlicensed state. The Retry After header returns the time (in seconds) after to retry the request again.

Query options

OData query options allow manipulation of data queries such as sorting, filtering, paging etc. They are sent in the query string of the request URL. A more detailed overview can be found here.

Custom query options should lighten the workload with the SmartStore.Net Web API, especially when you work with entity relationships.

SmNetFulfill{property_name}: Entities are often in multiple relationships with other entities. In most cases, an ID has to be set in order to create or change such relationships. Most of the time, however, this ID is unknown to you. To reduce the number of API round trips, this option can set an entity relationship indirectly. Example: You want to add a German address, but you don't know the ID of the German country entity which is required for inserting an address. Rather than calling the API again to get the ID, you can add the query option SmNetFulfillCountry=DE, and the API resolves the relationship automatically. The API can fulfill the following properties:

• Country: The two or three letter ISO country code. Example: SmNetFulfillCountry=USA

• StateProvince: The abbreviation of a state or province. Example for California: SmNetFulfillStateProvince=CA

• Language: The culture of a language. Example for German: SmNetFulfillLanguage=de-DE

• Currency: The ISO code of a currency. Example for Euro: SmNetFulfillCurrency=EUR