Resources

On Manifold a Resource represents an individual instance of your Product. In this document we'll walk through the requests necessary to creating, updating and deleting a Resource.

The primary actions your integration will implement are:

  • Resource provisioning: PUT /v1/resources/:id
  • Resource deprovisioning: DELETE /v1/resources/:id
  • Change plan: PATCH /v1/resources/:id

Always refer to the Provider API documentation for full API reference and definitions of advanced scenarios which Manifold supports.

Resource provisioning request

Manifold calls this endpoint to request the provisioning of a new Resource. Detailed information on this request can be found in the Provider API documentation.

Example Request

PUT /v1/resources/2687m6q19x63bt5krx5jgvpaq8c4m
X-Signature: L5sBInztA2FMUvDaiHlGze5Ocrd0P8-6oG7zWPDkK8UuxcNZ3PjT6IL-1N-7g-Vhonqy1sqxsi9CCKALzzTRAw RGMkX3O_z5jVrQhy9UteLydfEQaUD8WDurbEVZkWxHc fDdIKAxrdJoJQUbwnbRPBnsEjlvlMXsgIFKor-OgXGarZ_Y5yNm9G7nObQgKsWPBJxiHwPW4X5ihOELUfekcCg
Content-Type: application/json
Accept: application/json
{
  "features": {
    "age": 2,
    "hat_color": "red",
    "ready": true
  },
  "id": "2687m6q19x63bt5krx5jgvpaq8c4m",
  "plan": "ursa-minor",
  "product": "bear",
  "region": "all::global"
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json
{
  "message": "Your digital bear is ready"
}

Example Implementation (node.js)

This code is taken directly from the Node.js Sample Provider.

server.put("/v1/resources/:id", verifyMiddleware, function(req, res, next) {
  if (data.plans.indexOf(req.body.plan) === -1) {
    res.statusCode = 400;
    return res.json({ message: "bad plan" });
  }
  if (data.products.indexOf(req.body.product) === -1) {
    res.statusCode = 400;
    return res.json({ message: "bad product" });
  }
  if (data.regions.indexOf(req.body.region) === -1) {
    res.statusCode = 400;
    return res.json({ message: "bad region" });
  }

  var existing = db.resources[req.params.id];
  if (existing && !_.isEqual(existing, req.body)) {
    res.statusCode = 409;
    return res.json({
      message: "resource already exists",
    });
  }

  db.resources[req.params.id] = req.body;

  res.statusCode = 201;
  res.json({
    message: "your digital cat bonnet is ready",
  });
});

Examples are also available in other programming languages:

We support more languages in our Authentication libraries and SDKs.

Testing

Using Grafton you can generate requests against your integration to validate your Resource provisioning API handler.

Here is how you would run Grafton to generate the example Manifold request.

$ grafton test \
   --region='all::global' \
   --client-id=21jtaatqj8y5t0kctb2ejr6jev5w8 \
   --client-secret=3yTKSiJ6f5V5Bq-kWF0hmdrEUep3m3HKPTcPX7CdBZw \
   --plan-features='{"age":2,"hat_color":"red","ready":true}' \
   --plan=ursa-minor \
   --new-plan=ursa-major \
   --connector-port=3001 \
   --product=bear \
   http://localhost:8080

At this point in your implementation, you should expect to see lots of failures. The resource provisioning section should be passing. Even tests making sure incoming requests are authenticated and coming from Manifold (from Grafton while testing) should be passing.

Here is the expected Grafton output:

Grafton output provisioning resources

Resource deprovisioning request

Manifold calls this endpoint to request the deprovisioning of a Resource. Detailed information on this request can be found in the Provider API documentation.

Example Request

DELETE /v1/resources/2688u52yqfekhm7nzjyayqubkaw9j
X-Signature: L5sBInztA2FMUvDaiHlGze5Ocrd0P8-6oG7zWPDkK8UuxcNZ3PjT6IL-1N-7g-Vhonqy1sqxsi9CCKALzzTRAw RGMkX3O_z5jVrQhy9UteLydfEQaUD8WDurbEVZkWxHc fDdIKAxrdJoJQUbwnbRPBnsEjlvlMXsgIFKor-OgXGarZ_Y5yNm9G7nObQgKsWPBJxiHwPW4X5ihOELUfekcCg
Content-Type: application/json
Accept: application/json
# No Request Body

Example Response

HTTP/1.1 202 Accepted
Content-Type: application/json
{
  "message": "Your digital bear has been deleted"
}

Example Implementation (node.js)

This code is taken directly from the Node.js Sample Provider.

server.del("/v1/resources/:id", verifyMiddleware, function(req, res, next) {
  var resource = db.resources[req.params.id];
  if (!resource) {
    res.statusCode = 404;
    return res.json({ message: "no such resource" });
  }
  delete db.resources[req.params.id];

  res.statusCode = 204;
  res.end();
});

Examples are also available in other programming languages:

We support more languages in our Authentication libraries and SDKs.

Testing

Run the Grafton test command used when testing the provisioning of a resource above.

Now, with both provisioning and deprovisioning of resources implemented the Grafton output should have more passing tests.

Grafton output deprovisioning resources

Change plan request

Manifold calls this endpoint to request the change of plan of a Resource. Detailed information on this request can be found in the Provider API documentation.

Example Request

PATCH /v1/resources/2688u52yqfekhm7nzjyayqubkaw9j
X-Signature: L5sBInztA2FMUvDaiHlGze5Ocrd0P8-6oG7zWPDkK8UuxcNZ3PjT6IL-1N-7g-Vhonqy1sqxsi9CCKALzzTRAw RGMkX3O_z5jVrQhy9UteLydfEQaUD8WDurbEVZkWxHc fDdIKAxrdJoJQUbwnbRPBnsEjlvlMXsgIFKor-OgXGarZ_Y5yNm9G7nObQgKsWPBJxiHwPW4X5ihOELUfekcCg
Content-Type: application/json
Accept: application/json
{
  plan: 'new-plan'
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "message": "Your digital bear has been changed"
}

Example Implementation (node.js)

This code is taken directly from the Node.js Sample Provider.

server.patch("/v1/resources/:id", verifyMiddleware, function(req, res, next) {
  if (data.plans.indexOf(req.body.plan) === -1) {
    res.statusCode = 400;
    return res.json({ message: "bad plan" });
  }
  var resource = db.resources[req.params.id];
  if (!resource) {
    res.statusCode = 404;
    return res.json({ message: "no such resource" });
  }

  res.json({
    message: "Your digital bear has been changed",
  });
});

Examples are also available in other programming languages:

We support more languages in our Authentication libraries and SDKs.

Testing

Run the Grafton test command used when testing the provisioning of a resource above. All resources-only tests should now be passing.

Grafton output change plan