The SmartStore.Net Web API in detail

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 (like $filter, $top, $select etc.) and API specific options (like SmNetFulfillCountry) can be transfered through query strings. The web API offers two services. The OData service (path `/odata/v1/`) provides all entity related data and the API service (path `/api/v1/`) provides all remaining resources.

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 SmartStore-Net-Api-MaxTop header field.

A request body needs to be UTF8 encoded.

The OData metadata document

The metadata document describes the entity data model (EDM) of the OData service, using an XML language called the Conceptual Schema Definition Language (CSDL). The metadata document shows the structure of the data in the OData service and can be used to generate client code. It is the recommended overview for the consumer to indicate where to find a particular resource. To get the metadata document, send a

GET http://localhost:1260/odata/v1/$metadata

Request HTTP header fields

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

Accept (required): The wanted response format. Example for JSON: `application/json, text/javascript, /`. Example for XML: `application/atomxml,application/atomsvcxml,application/xml`

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

Content-Type and Content-Length (conditional): Necessary for the methods POST, PUT, and PATCH, if new data is send 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, because the content 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:

User-Agent: My shopping data consumer v.1.0
Accept: application/json, text/javascript, /
Accept-Charset: UTF-8
SmartStore-Net-Api-PublicKey: 0c6b33651708eb09c8a8d6036b79d739
SmartStore-Net-Api-Date: 2013-11-09T11:42:48.4715986Z
Content-Type: application/json; charset=utf-8
Content-MD5: lgifXydL3FhffpTIilkwOw==
Authorization: SmNetHmac1 +yvONYvJmQl19omu1uE3HVlQ7afd7Qqkk8DrNrfUbe8=

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 downward compatibility. The plugin version is typically increased when the API has been extended, for example when new ressouces were 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.

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

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

WWW-Authenticate: The name of the authentication method that failed. Note that CORS requests can lead to multiple of this header fields. The SmartStore.Net Web API returns `SmNetHmac1` if its authentication 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, for instance 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, for example for security reasons.

404 Not found: The requested ressource cannot be found.

406 Not Acceptable: The requested resource is only capable of generating content 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 sematic 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 ressource through the API is not implemented (yet).

Query options

OData query options allows to manipulate the querying of data like sorting, filtering, paging etc. They are send in the query string of the request URL. A more detailed overview can be found here.

Custom query options should lighten the work 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 to create or to change such a relation. But mostly this ID is unknown to you. To reduce the amount of API round trips this option can set an entity relation 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 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

Last edited Jul 14, 2014 at 3:18 PM by mgesing, version 3