using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.Serialization;
using System.ServiceModel;
using System.ServiceModel.Web;  // WebInvoke(), WebGet()
using System.Text;

/*
 * REST Web service follows four basic design principles:
 * + Use HTTP methods explicitly.
 * + Be stateless.
 * + Expose directory structure-like URIs.
 * + Transfer XML, JavaScript Object Notation (JSON), or both.
 * 
 * REST asks developers to use HTTP methods explicitly and in a way that's 
 * consistent with the protocol definition. This basic REST design principle 
 * establishes a one-to-one mapping between Create, Read, Update, and Delete 
 * (CRUD) operations and HTTP methods. According to this mapping:
 * + To create a resource on the server, use POST.
 * + To retrieve a resource, use GET.
 * + To change the state of a resource or to update it, use PUT.
 * + To remove or delete a resource, use DELETE.
 * 
 * POST and PUT are expected to have request bodies.
 * GET, PUT and DELETE can have parameters specified in URI used.
 * 
 * Stateless -- client (browser) must maintain any state required
 * 
 * REST Web service URIs should be intuitive to the point where they are easy to guess. 
 * Think of a URI as a kind of self-documenting interface that requires little, 
 * if any, explanation or reference for a developer to understand what it points to and 
 * to derive related resources. To this end, the structure of a URI should be straightforward, 
 * predictable, and easily understood e.g.
 * http://www.myservice.org/discussion/topics/{topic} where the user would specify
 * some {topic} to be searched in a database.
 * 
 * Different content can be returned as required by the client.
*/
namespace CorsService
{
    // NOTE: You can use the "Rename" command on the "Refactor" menu to change the interface name "IService1" in both code and config file together.
    // NOTE: You can use the "Rename" command on the "Refactor" menu to change the interface name "IMessageService" in both code and config file together.
    [ServiceContract]
    public interface IMessageService
    {
        // UriTemplates can be used with POST, GET, DELETE and PUT. 
        // URI templates allow you to map a URI or a set of URIs to a service operation.
        // e.g. say we have a C# method called SendMessage(), using the
        // UriTemplate="/postmessage" allows MessageService.svc/postmessage 
        // to be used instead of MessageService.svc/SendMessage allowing us to
        // change the method name later without modifying the service "seen" by
        // the user.
        // Note: If you want to use a URL instead of MessageService.svc, you need to
        // map a URL route in ASP.Net.
        // For GET, DELETE and PUT, you may also specify parameters to be read from the URL.         
        // UriTemplate = "SetMessage?thesender={sender}&themessage={message}"

        // Use WebInvoke for all methods other than GET (although it will also work for GET, use WebGet instead).
        [OperationContract]
        [WebInvoke(Method = "POST",                         // Specifies the HTTP method the service
                                                            // operation is mapped to.

               BodyStyle = WebMessageBodyStyle.Wrapped,     // Controls whether to wrap requests and 
                                                            // responses sent to and received from 
                                                            // the service operation i.e. whether parameters
                                                            // or returns are written within 
                                                            // infrastructure-provided XML elements. 
                                                            // Reqd, but has no baring in JSON

               RequestFormat = WebMessageFormat.Json,       // Controls how request messages are formatted.

               ResponseFormat = WebMessageFormat.Json,      // Controls how response messages are formatted.

               UriTemplate = "/postmessage")]               // URI, added to URL 
        // e.g. MessageService.svc/postmessage 
        // instead of 
        // MessageService.svc/SendMessage
        // POST is expected to have request body containing data
        void SendMessage(string sender, string recipient, string message);  // CREATE

        // Use WebGet for GET methods.
        [OperationContract]
        [WebGet(BodyStyle = WebMessageBodyStyle.Wrapped,
               RequestFormat = WebMessageFormat.Json,
               ResponseFormat = WebMessageFormat.Json,
               UriTemplate = "/readmessage")]
        [return: MessageParameter(Name = "Message")]            // Result is returned asa JSON name/value pair
        // By default, the name is the method name
        // with "Result" appended 
        // e.g. "ReadLastMessageResult":"some string"
        // Change this name to "hide" this method
        // "Message":"some string". Use this name in
        // JavaScript to recover the returned value.

        string ReadLastMessage();       // READ

        [OperationContract]
        [WebGet(BodyStyle = WebMessageBodyStyle.Wrapped,
               RequestFormat = WebMessageFormat.Json,
               ResponseFormat = WebMessageFormat.Json,
               UriTemplate = "/readmessage?id={msgId}")]    // GET can pass parameters in URL, 
        // (no request body)
        [return: MessageParameter(Name = "Message")]
        string ReadMessage(int msgId);      // READ

        // Out of interest, these will also work for a GET:
        //
        //[WebInvoke(ResponseFormat = WebMessageFormat.Json, 
        //          BodyStyle = WebMessageBodyStyle.Wrapped)]
        //
        //[WebInvoke(Method = "GET",
        //       BodyStyle = WebMessageBodyStyle.Wrapped,
        //       RequestFormat = WebMessageFormat.Json, 
        //       ResponseFormat = WebMessageFormat.Json)]
        //

        // More info here:
        // http://msdn.microsoft.com/en-us/library/bb943471.aspx

        [OperationContract]
        [WebInvoke(Method = "PUT",
               BodyStyle = WebMessageBodyStyle.Wrapped,
               RequestFormat = WebMessageFormat.Json,
               ResponseFormat = WebMessageFormat.Json,
                UriTemplate = "/putmessage?id={msgId}")]   // Read userId from URL, PUT is expected to have a
        // request body containing data (last argument is read
        // from body).
        [return: MessageParameter(Name = "Modifications")]
        EmailMessage ModifyMessage(int msgId, EmailMessage messageChanges);   // UPDATE

        [OperationContract]
        [WebGet(BodyStyle = WebMessageBodyStyle.Wrapped,
               RequestFormat = WebMessageFormat.Json,
               ResponseFormat = WebMessageFormat.Json,
               UriTemplate = "/readall?recipient={recipient}&keyword={keyWord}")]
        [return: MessageParameter(Name = "AllMessages")]
        EmailMessage[] ReadAllMessages(string recipient, string keyWord);    // READ

        [OperationContract]
        [WebInvoke(Method = "DELETE",
               BodyStyle = WebMessageBodyStyle.Wrapped,
               RequestFormat = WebMessageFormat.Json,
               ResponseFormat = WebMessageFormat.Json,
               UriTemplate = "/deletemessage?id={msgId}")]     // Read userId from URL (No request body)
        void DeleteMessage(int msgId);     // DELETE

        // Handle Raw JSON
        // http://stackoverflow.com/questions/2297903/generic-wcf-json-deserialization
        //[OperationContract]
        //[WebInvoke(Method = "POST",
        //        BodyStyle = WebMessageBodyStyle.Bare,
        //        RequestFormat = WebMessageFormat.Json,            WARNING: This didn't work
        //        ResponseFormat = WebMessageFormat.Json)]
        //void Test(System.IO.Stream rawJSON);

    }
}