HTTP is a stateless protocol. Each HTTP request from a client must contain all the information that is required by the server to process the request. The key advantage of this approach is that it frees up server resources that would otherwise be used in maintaining state information.

Instead, state information is maintained through the use of cookies. A cookie is a set of name-value pairs that the server sends back in response to an initial client request. A cookie could include information such as a session ID or an authentication token. Each subsequent client request must include the cookie, thus preventing the need for end-users to enter information such as login credentials for each request.

The OpenEdge.Net procedure library supports the use of cookies, enabling you to implement a stateful HTTP client. Cookies that are received from a server during a message transaction are stored in JSON format on a local disk on the HTTP client's host.

Each cookie has a domain and a path property that is mapped to a URI. When your HTTP client makes a request to a URI, all cookies associated with the URI are attached to the request. To enable this behavior, append the KeepCookies() method when building the HTTP client.
oClient = ClientBuilder:Build():KeepCookies():Client.

How cookies are stored

Cookies are stored in an instance of an OpenEdge.Net.HTTP.ICookieJar class. The following points summarize how these cookies are stored:

  • Cookies must be associated with a domain. This domain may be prefixed with a wildcard '.' .
  • If the cookie itself has no domain, the request's host domain is used.
  • The cookie domain and the request host domain must be the same.
  • Cookies that have no expiration date are considered session cookies and are deleted when the CookieJar is deleted/cleaned up. Session cookies can be cleaned using the CleanSessionCookies() method.

Cookies are retrieved from the cookie jar and attached to an HTTP request automatically based on the following criteria:

  • The request's host is identical to cookie's domain, or the host matches the cookie's domain.
  • The request's URL path begins with the cookie path.

How to read and write cookies

To read/write cookies on requests and responses, use the methods from the IHttpMessage interface as shown in the following code sample.

/** Adds a cookie to this message  
    @param Cookie The cookie to add. */ 

METHOD PUBLIC VOID SetCookie(INPUT poCookie AS Cookie).  

/** Returns all the cookies for this message
    @param Cookie[] An array of cookies  
    @return integer The number of cookies returned */ 

METHOD PUBLIC INTEGER GetCookies(OUTPUT poCookies AS Cookie extent).  

/** Removes a cookie from this message  
    @param Cookie The cookie to remove. */ 

METHOD PUBLIC VOID RemoveCookie(INPUT poCookie AS Cookie).   

/** Indicates whether a cookie exists for this message  
    @param Cookie The cookie to check
    @return logical True if this message contains the cookie */ 

METHOD PUBLIC LOGICAL HasCookie(INPUT poCookie AS Cookie).  

/** Removes all cookies from this message */  

METHOD PUBLIC VOID ClearCookies().
Note: You can inspect an individual cookie by casting the cookie to a string (using ToString(), STRING(oCookie), or MESSAGE oCookie).

API reference documentation

To view the list of methods that you can use on a Cookie object, refer to the OpenEdge.Net.HTTP.Cookie reference documentation.