Encode Content-Type Form Data

Referencing Content-Types in GraphQL schema to POST form data.

HTTP Methods such as POST or PUT requests include a Content-Type to represent the media type being sent in an HTTP request. Two of the most common Content-Types are supported for the encode form data feature.

  • application/x-www-form-urlencoded
  • application/json

What does it mean to Encode Form Data?

Encoding form data is not easy. The data can be appended in many different ways and it must be computer readible with urlencoded formatting. With the Encoding Form Data feature of StepZen, many of the difficulties and issues found in form data sytax are eliminated and automatted for the developer.

Depending on the type of Content-Type being sent in an HTTP POST method, there are explicit ways the resources must be sent to be successful.

Content-Type: application/x-www-form-urlencoded is requesting the data to be one long query string appended to the url.

https://api.example.com/oauth/v1/token?grant_type=refresh_token&client_id=$client_id&client_secret=$client_secret&refresh_token=$refresh_token

Content-Type: application/json is requesting the data to be send as a json object in the body of the request.

{
  "grant_type": "string",
  "client_id": "string",
  "client_secret": "string",
  "refresh_token": "string"
}

How to encode form data on an HTTP POST Method

The StepZen @rest directive supports the HTTP POST method and header parameters in a GraphQL schema to generate the encoded form data.

Take the cloudmersive example below. This GraphQL Query compares the similarity of two strings and returns the similarity score.

"""
Perform Semantic Similarity Comparison of Two Strings
Analyze two input text strings, typically sentences, and determine the semantic similarity of each.  Semantic similarity refers to the degree to which two sentences mean the same thing semantically.
"""
cloudmersive_Analytics_Similarity(
    """
    Authorization with APIKey
    """
    cloudmersive_apiKey: Secret!
    TextToAnalyze1: String
    TextToAnalyze2: String
  ): Cloudmersive_SimilarityAnalysisResponse
    @rest(
      endpoint: "https://testapi.cloudmersive.com/nlp-v2/analytics/similarity"
      method: POST
      postbody: ""
      contenttype: "application/json"
      headers: [{ name: "ApiKey", value: "$cloudmersive_apiKey" }]
    )

Content-Type: application/json

The configuration properties are essential to properly executing the StepZen @rest directive.

  • endpoint: The REST endpoint that will be used to populate the query result.
  • method: The action the request is making to the REST endpoint.
  • headers: Custom header parameters to pass cookies and authentication requests.
  • contenttype: Indicating the media type the request is sending to the REST endpoint.
  • postbody: The resource data being sent in the body of the request.

Breaking down the cloudmersive query example, there are three graphql arguments.

cloudmersive_apiKey: Secret!
TextToAnalyze1: String
TextToAnalyze2: String

These arguments will be used as variables in the @rest request, and the cloudmersive_apiKey is explicitly declared in the headers configuration property with the $.

headers: [{ name: "ApiKey", value: "$cloudmersive_apiKey" }]

Now the question lies, where do we inject the TextToAnalyze variables in the @rest request. Well, this is where the encoded form data feature comes into action.

The configuration properties below tell StepZen that this method can encode the form data.

method: POST
contenttype: "application/json"
postbody: ""

Notice Content-Type is application/json and postbody is empty, so StepZen recognizes these configurations and injects the all undeclared variables into the body of the request. cloudmersive_apiKey is declared in the header configuration, so it is left out of the body.

{
  "TextToAnalyze1": "string",
  "TextToAnalyze2": "string"
}

Query

Now by running the query below, the proper request should be sent to the endpoint https://testapi.cloudmersive.com/nlp-v2/analytics/similarity and a response for similarity should be returns.

query MyQuery($cloudmersive_apiKey: Secret = "") {
  cloudmersive_Analytics_Similarity(
    cloudmersive_apiKey: $cloudmersive_apiKey
    TextToAnalyze1: "running around the block"
    TextToAnalyze2: "running around the corner"
  ) {
    SentenceCount
    SimilarityScoreResult
    Successful
  }
}

Query result

{
  "data": {
    "cloudmersive_Analytics_Similarity": {
      "SentenceCount": 2,
      "SimilarityScoreResult": 0.0019565322436392307,
      "Successful": true
    }
  }
}

Content-Type: application/x-www-form-urlencoded

Using the same examplecloudmersive_Analytics_Similarity, if the endpoint https://testapi.cloudmersive.com/nlp-v2/analytics/similarity now wanted application/x-www-form-urlencoded as the Content-Type, the only change that would be needed in the schema would be the contenttype configuration.

The existing configuration

contenttype: "application/json"

Changes to this configuration

contenttype: "application/x-www-form-urlencoded"

That is it. The configuration change will be recognized and now instead of creating a body property, the undeclared variables will be appended to the url as a long urlencoded string!

https://testapi.cloudmersive.com/nlp-v2/analytics/similarity?TextToAnalyze1=running%20around%20the%20block&TextToAnalyze2=running%20around%20the%20corner

Important caveats

  • Using other Content-Types will not encode the data.
  • postbody is an optional parameter for this feature. It does not need to be included to encode the data. The examples above include postbody to show how the body of an HTTP Method is included in the @rest directive for encoding form data.

  • Renaming the arguments is currently not supported for encoding form data. If a field needs to be renamed, it should be declared in the postbody or as a utm parameter.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.