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

Managing plan changes

If a user wishes to change their plan, by default all plans are available for selection. In some cases though, you as a service provider, may wish to prevent certain upgrade or downgrade paths.

The first and best tool you have available to you is in Manifold's configuration for your product. We can setup a per plan whitelist of plans that can be changed to. Please communicate with us to get that configured when we start to stage your product in our Marketplace.

Your second option is to block the plan change request by returning a 400 error code from the PUT resource request as defined here this can be done in addition to setting the resize constraints within our Marketplace to give you more peace of mind, but also to block plan feature changes in the case of a custom plan.