.NET M2X API Client

The AT&T M2X API provides all the needed operations to connect your device to AT&T's M2X service. This client provides an easy to use interface for .NET.

Getting Started

1. Signup for an M2X Account.
2. Obtain your Master Key from the Master Keys tab of your Account Settings screen.
3. Create your first Data Source Blueprint and copy its Feed ID.
4. Review the M2X API Documentation.

Please consult the M2X glossary if you have questions about any M2X specific terms.

Installation and System Requirements

The M2X API .NET Client library is a regular MS VS 2012 Class Library. The only dependency is .NET Framework version 4.5 which can be downloaded: http://www.microsoft.com/en-us/download/details.aspx?id=30653.

Just add it as an Existing Project into your VS solution or if you are using a different version of Visual Studio you can create a new class library project and include the content of the ATTM2X/ATTM2X folder into it. Here is the list of additional references you will need to add in this case:

• System.Web
• System.Web.Extensions

Besides the API Client library, this solution also includes a console test app which contains multiple examples of library usage, which can be found here: ConsoleTest folder.

System requirements match those for .NET Framework 4.5.

• Supported Operating System:

   Windows 7 Service Pack 1, Windows Server 2008 R2 SP1, Windows Server 2008 Service Pack 2, Windows Vista Service Pack 2
   Windows Vista SP2 (x86 and x64)
   Windows 7 SP1 (x86 and x64)
   Windows Server 2008 R2 SP1 (x64)
   Windows Server 2008 SP2 (x86 and x64)
  

• Hardware Requirements:

   1 GHz or faster processor
   512 MB of RAM
   850 MB of available hard disk space (x86)
   2 GB hard drive (x64)
  

Note: Windows 8 and Windows Server 2012 include the .NET Framework 4.5. Therefore, you don't have to install this software on those operating systems.

Library structure

Currently, the client supports API v1 and all M2X API documents can be found at M2X API Documentation. All classes are located within ATTM2X namespace.

• M2XClient: This is the library's main entry point. In order to communicate with the M2X API you need an instance of this class. The constructor signature includes 2 parameters:

apiKey - mandatory parameter. You can find it on your M2X Account page Read more about M2X API keys in the API Keys section of M2X API Documentation.

m2xApiEndPoint - optional parameter. You don't need to pass it unless you want to connect to a different API endpoint.

Client class provides access to API calls returning lists of the following API objects: blueprints, batches, data sources, keys, feeds.

• Get the list of all your keys:

   	var client = new M2XClient("[API Key]");
   	var keys = client.GetKeys();
   	Console.WriteLine("Number of keys = " + keys.keys.Count);
  

There are also a number of methods allowing you to get an instance of individual API object by providing its id or name as a parameter:

• Get an instance of a feed:

   	M2XFeed feed = client.GetFeed("[Feed id]");
   	var location = feed.GetLocation();
  

• Blueprints

  Use GetBlueprints method of M2XClient to get the list of blueprints of your M2X account. API spec

  Use GetBlueprint method of M2XClient to get an instance of M2XBlueprint class.

  • Creation API spec

    	var blueprintData = client.CreateBlueprint("Blueprint", M2XVisibility.Public, "Blueprint description"); 
    	M2XBlueprint blueprint = m2x.GetBlueprint(blueprintData.id);
    

  • Update API spec

    	blueprint.Update("Blueprint updated", M2XVisibility.Private);
    

  • Removal API spec

    	blueprint.Delete();
    

  • Get blueprint details API spec

    	var blueprintData = blueprint.Details();
    

• Batches

  Use GetBatches method of M2XClient to get the list of batches of your M2X account. API spec

  Use GetBatch method of M2XClient to get an instance of M2XBatch class.

  • Creation API spec

    	var batchData = client.CreateBatch("batch", M2XVisibility.Public, "batch description");
    	M2XBatch batch = m2x.GetBatch(batchData.id);
    

  • Update API spec

    	batch.Update("batch updated", M2XVisibility.Private);
    

  • Removal API spec

    	batch.Delete();
    

  • Get batch details API spec

    	var batchData = batch.Details();
    

  • To get all the datasources in this batch use GetDataSources method API spec

    	var dataSources = batch.GetDataSources();
    

  • To create a data source associated with the batch use AddDataSource method API spec

    	var datasourceData = batch.AddDataSource("[data source serial number]");
    

• Data Sources

  Use GetDataSources method of M2XClient to get the list of data sources of your M2X account. API spec

  Use GetDataSource method of M2XClient to get an instance of M2XDataSource class.

  • Creation API spec

    	var dsData = client.CreateDataSource("test data source", M2XVisibility.Public, "data source description");
    	M2XDataSource dataSource = m2x.GetDataSource(dsData.id);
    

  • Update API spec

    	dataSource.Update("data source updated", M2XVisibility.Private);
    

  • Removal API spec

    	dataSource.Delete();
    

  • Get details API spec

    	var dsData = dataSource.Details();
    

• Keys

  Use GetKeys method of M2XClient to get the list of API keys of your M2X account. API spec

  Use GetKey method of M2XClient to get an instance of M2XKey class.

  • Creation API spec

    	var keyData = client.CreateKey("test key", new[] { M2XClientMethod.POST, M2XClientMethod.GET });
    	M2XKey key = m2x.GetKey(keyData.key);
    

  • Update API spec

    	key.Update(new { name = "updated name", permissions = new[] { "POST", "GET" } });
    

  • Removal API spec

    	key.Delete();
    

  • Get details API spec

    	var keyData = key.Details();
    

  • Regeneration. Method generates new key id. API spec

    	var keyData = key.Regenerate();
    

• Feeds

  Use GetFeeds method of M2XClient to get the list of feeds of your M2X account. API spec

  Use GetFeed method of M2XClient to get an instance of M2XFeed class. Feeds creation is done when creating a DataSource, Blueprint or Batch. Update and removal is not supported by the cloud API.

  You can get a feed associated with a blueprint, a batch or a data source by calling GetFeed method of the corresponding class: M2XBlueprint, M2XBatch or M2XDataSource.

    	M2XFeed feed = dataSource.GetFeed();
  

  • Feed location

    Get feed location API spec

    	var locationData = feed.GetLocation();
    

    Update feed location API spec

    	feed.UpdateLocation(-37.9788423562422, -57.5478776916862, "test location", 500);
    

  • Feed logs API spec

    	var logData = feed.Log();
    

  • Feed streams

    Get the list of feed streams: API spec

    	feed.GetStreams();
    

• Streams

  Use GetStreams method of M2XFeed to get the list of streams of your feed. API spec

  Use GetSteam method of M2XFeed to get an instance of M2XStream class.

  • Creation and update is implemented as one method API spec

    	M2XStream stream = feed.GetStream("[stream name]");
    	stream.CreateOrUpdate(new { unit = new { label = "Celsius", symbol = "C" } });
    

  • Removal API spec

    	stream.Delete();
    

  • Get details API spec

    	var streamData = stream.Details();
    

  • Pull stream values API spec

    	var values = stream.GetValues();
    

  • Post values to stream API spec

    	stream.PostValues(new[] { new M2XPostedValue { At = DateTime.Now, Value = "36.6" } });
    

• M2XAPIException

All API errors are wrapped in M2XAPIException object which has the following properties:

• Message - error message.

• Url - the URL of API call which caused this error.

• StatusCode - HTTP status code.

• ValidationErrors object - returned by some API methods. Contains additional error details.

• Example. The following API response:

   	422 Unprocessable Entity
   	{ "message": "Validation Failed",
   	"errors": { "latitude": ["not_present"], "longitude": ["not_valid"] } }
  
   gets converted into the following M2XAPIException instance:
   	
   	Message = "M2X API error code 422: Validation Failed"
   	Url = "[API call URL]"
   	StatusCode = 422
   	ValidationErrors = { "latitude": ["not_present"], "longitude": ["not_valid"] }
  

ConsoleTest application

The console test application included into ATTM2X solution has a lot of examples for the most of M2X API methods.

Usage:

	ConsoleTest.exe [APIKey]

Replace [APIKey] with Master Key of your M2X account.